On 2019-09-12 22:29:04 +0200 (+0200), Dominig ar Foll (Intel Open Source) wrote:
but if we want to motivate people to write more documentation we need to find a simpler way. To write docs we need to be able to at least check the display of a page before committing in a simple way.
If the environment is complex to reproduce and to debug, then we should have, at least, somewhere a web page creation service. How reviewer will check that was is proposed is OK and looks fine ?
It's a serious issue that needs to be addressed with urgency. [...]
It's an environment optimized for embedding documentation in and extracting documentation from software written in the Python programming language. StarlingX borrowed its documentation workflow from OpenStack, whose software is written almost entirely in Python (the OpenStack community wanted to make sure that its developers didn't have any excuse to avoid writing and updating documentation). With this, of course, comes the complexity of getting a Python software development environment going, which I can understand might seem odd or challenging to folks who are not computer programmers, or perhaps who focus on other languages are are disinterested in getting acquainted with Python language ecosystem conventions and norms). Regardless of what tooling is used to manage documentation, I expect that the basics of making it possible to write in a simple markup language, being able to propose and review changes to documentation prior to publication, and recording changes under annotated revision control are still beneficial, as is the ability to take advantage of continuous integration and deployment automation to reject proposed changes for common errors or style deviations and to publish them automatically on approval. The current solution meets those needs, but they could still be met by using different documentation build tooling too as long as someone writes Zuul jobs to install and run that instead of python+tox+virtualenv+sphinx. -- Jeremy Stanley