On 15/12/2016 17:21, Sebastian Huber wrote:
It would be quite nice if we can write BSP README files in
reStructuredText placed in the Git repository that show up on the wiki.
I support using the ReST format.
I am not convinced the Wiki is the best place to land this
documentation. These READMEs are really good documentation and we need
better BSP documentation. Having it included in the release
documentation would be nice.
We already have BSP documentation on the wiki. We have also BSP
documentation in the README files. What we really need is to document
things only once for a specific domain and present it to the user where
it expects the information.
I agree.
Using README files in ReST format gives us the opportunity to present
the same information
* in the source tree as a simple text file,
* in the wiki via plug-in, and
* in a user manual via sphinx.
I do not think the wiki is needed if a manual contains the needed
content and too many places confuses the work flow for users. I also
feel generated doco on a wiki is confusing because users of a wiki
expect to be able to change the content on the wiki and there is no back
flow to the README source.
The rtems-doco.git repo is user focused and not design or implementation
documentation. I see the wiki holding specific use cases for someone
doing a specific thing as a how to.
Joel and stated to me he would like to see more of the wiki content have
related to Quick Start etc moved into the User Manual to strength it and
make it easier for users and I agree. For example who is going to search
the wiki and remove all SIS BSP related issues how it has been removed
from the master branch? The SIS BSP is still in 4.10 and 4.11 so does
removing those references mean users of those versions have lost a
documentation resource?
Why not add this documentation to the rtems-docs.git repo?
Why not move the documentation back into the rtems.git repo?
The docs are a boarder set of topics than just the kernel and it
complicates constant integration.
I think is it very nice if you have the BSP sources and a basic
documentation in the same directory.
How often do these files change? I suspect infrequently because they
impact on the user if changes are made. The type of information I see
being in the documentation is user focused so it is about configuration
and management of the BSP and this is a contract between the user and
BSP that should not change without careful consideration.
Having the BSP doco in the rtems-docs.git repo means we can make and
publish the doc formats we support, ie HTML and PDF, because that repo
has all the support needed to build the documentation. It is also
supported as part of the release procedure.
If the desire is to keep this documentation close to the source, which
is attractive, and using rtems-docs.git is a good idea then we need to
figure out how to handle this.
I still think that it was not good to move the documentation sources
into a separate repository.
I do not agree. Documentation is more than just the RTEMS kernel. We
need to cover Eclipse, debugging, tools not in the kernel source tree,
eco-systems, libbsd, applications, building system issues for
applications and pushing these down into the RTEMS kernel source is
confusing for those topics creating unrelated commit churn which then
effects constant integration.
We have a lot of copy and paste in the
documentation and duplicated information in the header files and the
documentation files.
I would hope the amount of user focused documentation in the headers is
small. We need formal documentation for all the APIs we support and I
would like to see us adding examples to each function to show it's usage.
One option to simplify this would be a XML file
I tolerant XML, I do not love it. Personally I find INI files a simpler
input format to handle when a user needs to maintain it and INI files
are OK in some cases and not great in others. :)
which defines and documents the RTEMS interfaces (data types, functions,
defines, macros, etc.) and then use a generator to produce header (maybe
even with Doxygen comments) files, documentation files and also test cases.
I would prefer the user documentation be user focused and we aim at just
the supported API functions. These are the functions that do not and
cannot change across releases unless there is a documented, considered
and traceable reason. I am fine with internal, implementation and test
case documentation being on a wiki, deoxygen or what ever works best and
being generated.
Chris
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
