Documenting framework features and descriptions
We have written a custom software framework and it has grown to the point where we are ready for documentation. This documentation will be used by other developers to share knowledge. I am concerned with how to do the documentation for the features and descriptions.
My co-worker suggested a Word document with sections and a feature matrix. I am not too keen on that and would like to find an alternative. What have you used in the past, good and bad parts? I couldn't find anything in particular on documenting features, I guess looking at something like a bootstraps website is a good start but creating a website for this is not doable. Are there any charts that may aid in documenting the features?
Edit: Custom Software Framework for building Web Applications. The framework is built using C# + .Net...
This post was sourced from https://writers.stackexchange.com/q/48174. It is licensed under CC BY-SA 4.0.
3 answers
Personally I use Latex, more specifically pdflatex, which is free to download. It is text-based, learning it will probably take a week or two, but there are online examples and help through StackExchange.
The advantage is you can produce charts, diagrams, flowcharts and anything else you want (art for example) using other packages, in their own PDF files, and then "include" them in your documentation.
For myself, as a research scientist, some of my graphs can be complex and we use special packages to produce them, and not always the same packages. I might produce a few with just a spreadsheet, and some diagrams with Draw, and others with a specialty package designed to draw, say, molecular diagrams, or engineering diagrams.
Latex itself is the best way (by far IMO) to render complex mathematical equations, and to back-reference in the text or build a bibliography.
In technical fields (STEM) at least I think this is the package most used in academia and research, in the four universities I have attended or worked at, it is difficult to finish a PhD in a STEM field without being versed in Latex.
0 comment threads
I would definitely not recommend using Word for this. It is just not what it was designed to do.
There are multiple documentation systems that have been developed specifically for the purpose of writing developer documentation. They provide frameworks and tools, and, what may be more important to you at this stage of the project, examples of what works.
It is impossible to say which would be preferable for your particular project without knowing far more about it. But as a place to start I would suggest that you investigate Sphinx. Sphinx is the tool that was developed to document the python programming languages and the various libraries, modules, and platforms that are associated with it. It is widely used for similar projects.
A lighter weight, and therefore less capable but simpler alternative is Jekyll which is also used for documenting many software products. It is a more generic model, so it won't give your as much help and guidance, but it is very straightforward to use and you could draw on the examples of many other organizations.
0 comment threads
If you are documenting programming interfaces (APIs), look for a tool that generates documentation from comments in the code. This allows you to place the documentation right with the code, and the tool extracts the function interfaces from the code directly. This means there's one source of truth, rather than having separately-created documentation that you copied the interfaces into...once upon a time, and then the code changed but you didn't notice.
Tools like this (Doxygen is one example) are good for low-level "tactical" documentation, but comments in your code aren't enough to provide the overviews, guides, and examples that you'll also need. For this other documentation, you have two choices: add that documentation into the (for example) Doxygen build by adding documentation files to your source code, or write separate documentation and link or include the API documentation in the published output.
Your decision is affected by the answers to the following questions:
- Who is writing the documentation? Are the writers trusted to modify files in the source tree?
- Who is the documentation for and how will you publish it? Do you need to ship something or just post it on the web somewhere? Or is it internal and you can use a wiki?
- How often do you publish new versions with breaking changes? If you need to update doc a few times a year, separate API and other documentation is probably fine. If you're making (and publishing) big changes to the interface in each sprint, that might push you more toward tight integration between the doc and the code.
It sounds from your question like your documentation is for a library of components of some sort. If that's correct, then regardless of what tool or format you use, find or create a template that you can use to create topics for new features/interfaces/components. This will help you make sure you covered all the important points and in a consistent order or format.
0 comment threads
0 comment threads