Learn More
Resend Email
2
Nmeri17
2y

Why are big software documentations versioned by url rather than adding the most current update to relevant sections and signifying it as such?

1) only select parts of the software is updated in between major version updates. Why duplicate the entire docs for only sparingly updating those parts?

2) references hold versioned urls that could go out of date. I imagine it takes some effort to have a banner on each page indicating whether this is the most up-to-date version of the software

3) deprecated documentation is redundant since it's no longer maintained. Why does it continue to exist? Not everyone has upgraded, you say. That, and I guess, it costs the maintainers nothing to have an idle folder 6 major versions behind the most recent

I already have a folder for my v1 but I'm considering pulling them into a permalink. What challenges or disadvantages are there to doing so?

question

versioning

documentation
Favorite
Ranter
Comments
  • 2
    2y
    Isn't it best if each version of the software has a complete set of documentation? Cross referencing to see which bit of the docs is current - or related to the particular version that [a] runs on your hardware [b] works reliably and [c] is compatible with plug-ins, extensions and other software - can waste a lot of time. For me, it's easiest/best to be able to go direct to the full set of docs for the version you have.
  • 0
    2y
    @spongegeoff none of the constraints you mentioned are applicable in the stack I come from. The only thing that changes is the language version, which can easily be noted beside the newly introduced feature

    The php documentation has used this pattern for decades. All their links are permalinks
  • 2
    2y
    We use a product called bamboo at our office. It's a competitor to Jenkins. I notice its help pages have the version number on the url. Once in awhile, I'll be reviewing the documentation, and I'll find something cool. Then I'll test it. It won't work. One day, I kept the help page up and noticed I was pointed to the wrong version. When I opened the proper website at that same point, it said 'not supported by this version'

    I like the idea of versions help, but if you go down that route, version track all of it. I'm my case, there was a link to another topic, which wasn't versioned. That page had a link to the versions notes, but it took me to the wrong version.

    Grr... spaghetti docs
  • 0
    2y
    I guess it's plausible for reference documentation, where functions and classes change far less frequently. Framework documentation (which I'm asking about) is discussed by feature, which is subject to change or include slight variations in between releases (also more frequent than at the language level)
  • 0
    2y
    ah.. you talk about PHP.
    that explains it.
  • 0
    2y
    @thebiochemic
Related Rants
devRant © 2021 Hexical Labs LLC
Privacy Policy  |  Terms of Service
Add Comment