Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Documenting framework features and descriptions

+2
−0

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...

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/48174. It is licensed under CC BY-SA 4.0.

0 comment threads

3 answers

You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.

+2
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+1
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+1
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »