8

I'm creating a program in python that simulates an ideal quantum computer. It is on GitHub, and while it is not anywhere near complete yet, I don't know how much documentation I need to include, and where to put it.

For example, do I need to include information about how the code itself works? About how to use the program? How in-depth does it need to be? I also have no idea where to put this on GitHub - I guess in the readme file, but I didn't know if there was a better place to put it.

Improve this question
3
  • 1
    I wanted to accept both answers because they were both so helpful. Thanks everyone!
    – auden
    Dec 6, 2016 at 12:15
  • I think this is a wonderful and useful question! Welcome to Open Source Stack Exchange! :)
    – Zizouz212
    Dec 6, 2016 at 21:47
  • @Zizouz212, thanks, glad to here that it is good to have here. =)
    – auden
    Dec 6, 2016 at 22:33

2 Answers 2

Reset to default
12

Think of it this way:

how much documentation would I like to be available when I visit an open source project?

Answer: a lot

how much documentation is enough?

Answer: there is never enough documentation!

Now there are several things to consider:

Making a great first impression matters

For this you want to have a clear one liner that describes your project and a good README. These will be the first documentation that a user will see. On Github this means using markdown or ReST to create a concise and comprehensive README with several questions that I would expect to find answers about your project:

  • explain why this project exists?
  • what does your code?
  • how to use it in a minimal way? and how does it works at a high level?
  • is the code stable and tested? if you have a CI running your tests, put CI badges in that README. Tests serve also as documentation for your code.
  • how to download and install it including URLs to its home page, repos?
  • how can I get support? (e.g. tickets, mailing lists, IRC, etc)
  • what is the license for this code?
  • URLs to more detailed documentation (when this is ready... you may not it have right at the start)
  • What are alternative projects that do the same thing?
  • How can I contribute to your project? Do you accept pull requests? Patches by email? What do you expect from a patch in terms of coding standards, etc

That's a lot but I would expect this. Here are some examples:

(Note: I am involved with these projects and I do not claim their README is perfect, far from it).

Built-in UI & CLI documentation

Next you want making your code as easy to use as possible. If you have a UI or a command line interface, make sure that this contains as much built-in usage help and documentation as needed. If this is a library, make sure that your functions are documented using your language conventions (e.g. this would be docstrings for Python).

Tests are documentation

Next you want tests: test code serves as a great documentation especially for libraries and beside that they are kinda useful... Running the tests on Travis, Appveyor, Circle and similar is important of course.

Formal manuals and documentation

Next is actual formal documentation. The convention is to store this in a docs or doc top level directory. On Python, most folks use ReST for writing docs. You would want to cover a few things:

  • a usage guide
  • an installation guide
  • if needed a troubleshooting guide
  • some FAQ
  • an API documentation: if your project is also a library you should generate an API documentation based on the documentation present in the code. For Python, this would mean using something like Sphinx to generate the doc.

You should publish that documentation on a web site. https://readthedocs.org/ is a great resource for this.

Here are a few decent examples:

I hope this helps for a start!

Improve this answer
4
  • A very good answer; three remarks: "test code serves as a great documentation especially for libraries" seems to me like it significantly depends on the particular type of library/project we are looking at. What we can say is that tests are examples of usage, and IMHO that just highlights how for some applications, examples are self-explanatory, while for others, even a comprehensive list of examples is rather cryptic without some additional documentation. I would give the "installation guide" rather a higher priority (if one is needed at all). Lastly, the docs should indeed be ...
    – O. R. Mapper
    Dec 8, 2016 at 19:17
  • 1
    ... accessible in a web-based way. But rather than a general repository like Read the Docs, I would expect to find a web-based view of the documentation along with the project (e.g. on Github Pages, if we're talking about a Github-hosted project). Uploading the docs to 3rd-party archives (just like cataloguing the code in code search engines, creating packages for one's favourite packaging system, etc.) is worthwhile, but rather an "advanced" step after the straightforward publication on the project site.
    – O. R. Mapper
    Dec 8, 2016 at 19:20
  • Supplementary: "rather than a general repository like Read the Docs, I would expect to find a web-based view of the documentation along with the project" - after having a look at the Read the Docs site, I find this to be doubly important as the choice of document formats for documentation supported by Read the Docs seems rather limited. Maybe I'm missing something, but it seems they only support Markdown and reStructured Text. So much for publishing HTML-based MSDN-style documentation on .NET libs generated by Sandcastle there.
    – O. R. Mapper
    Dec 8, 2016 at 19:39
  • @O.R.Mapper these are all excellent comments. Do you want me to turn this answer in a wiki? Note that FWIW, readthedocs is pretty much the standard in the world of Python which was the question is about.
    – Philippe Ombredanne
    Dec 9, 2016 at 10:15
5

There's really no standard; it's all up to you.

For example, do I need to include information about how the code itself works? About how to use the program? How in-depth does it need to be?

I generally write documentation primarily for users. That means including information on:

  1. What problem this solves ("Why would I use this?")
  2. How to install it
  3. How to use it

If the program is sufficiently large that it's not easy to get into as a new developer, then you might want to also include developer information, like an architecture diagram.

I also have no idea where to put this on github - I guess in the readme file, but I didn't know if there was a better place to put it.

That's a great place, because it's one of the first things they'll see. Another good option is a website that's listed as the project link in GitHub - GitHub Pages and Read the Docs are good options for this, but really whatever is easiest is fine.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.