Improve documentation

  • Testers

    For the FogApi powershell module I’m using read the docs with mkdocs.
    You can see the simple .readthedocs.yml and mkdocs.yml config files in my repo for it here
    The published version is here

    Granted, documenting a powershell module is a bit simpler since it’s mostly documenting the functions and what they do and can be generated from comment blocks in-line in the code.

    I think readthedocs requires (or is at least by default designed) to have the docs in the same repo to help maintain versions. I don’t have versioning setup though. There’s a page for setting up based on branches and I believe releases and tags as well. I believe it could still be done in a separate repo though, might just require more effort to link versions. Or it could be easier cause you just create a new version each time a version of fog is released and whatever the documentation said at that point is the documentation for that version.

    There is also githubpages as a similar option, I found readthedocs a bit easier for my purposes.

    I also remember @Joe-Schmitt setting up for fog-too I think. That’s how I knew what readthedocs was when I wanted to make public documentation for my powershell code.

    I would love to help out with getting this setup and some things documented.

    Maybe we could have something that grabs stuff from the forums, or maybe just a label/tag we can report against to periodically go through and add to documentation

  • I will create these accounts and will let you know.

    I have to dig some deeper into sphinx/readdthedocs, but I know many projects have documentation for different versions.

    Take Ansible as example: In the top left part you can choose a version. I think this would be handy for Fog as well. A new release: a new set of documentation where you can make the changes that are specific for that version.

  • Senior Developer

    @Wayne-Workman Good point. Though I fear we don’t get our act together to really update the documentation accordingly. Having it all in one repo doesn’t force us to actually update it.

    On the other hand we can still tag a particular state of the documentation in a separate repo to match that same version in the fogproject code repo.

    I just remembered that Joe actually had started a repo and readthedocs project some time ago but we never got into it…

    @Jurgen-Goedbloed Do you have an account with github and readthedocs yet?

  • Here’s the benefits I can think of for keeping them together.

    • a certain version of the documentation is locked together with the corresponding code it’s documenting.
    • When you checkout an older version of fog, you’re also checking out the older corresponding documentation, and if you’re checking out a newer fog, you’re checking out newer corresponding documentation.
    • When comparing differences between an older version and newer one, it may be easier for some to see the changes by looking at the differences in documentation.

  • Senior Developer

    @Wayne-Workman said in Improve documentation:

    why do you think documentation should be in a separate repo?

    Good question. Hmm. Just thought it might be easier to keep track of changes when code and docu are not all in one repo.

  • @Sebastian-Roth why do you think documentation should be in a separate repo?

  • Senior Developer

    @Jurgen-Goedbloed This is really awesome you ask about this!! I was thinking about this the Last days and was planing to ask for help in the forums to improve documentation. So I definitely vote for this! Let’s do it…

    Probably best if we create a new repo for the documentation in
    I would think.

Log in to reply