https://voxpupuli.org/ logo
Join Slack
Powered by
# sig-documentation
  • v
    (not sure I'm clear)
  • v
    ah well, the time it took to type, you answered my question :)
  • m
    Having the last updated footer actually show when the file was last updated is very useful, we still have a lot of pages that are puppet 5.5 vintage and it's not obvious without some kind of indication
    ☝️ 1
  • v
    yes, page per page I understand. The "building date" is a bit less important, especially as it's automated. That's not evident when you have a first look at the source
  • m
    you mean looking at the source it git? We might be able to do something in front-matter to better show "Published" and "Last updated" we have the data, something similar to what we have on voxpupuli
  • v
    the last one is confusing
  • v
    "published in 2021, updated in 2025" ?!?
  • v
    I get it for a blog article that you edit and where the original date is important
  • v
    but for docs ?
  • v
    what is important (to me) in docs is "which software version is it relevant to" (be it 8.x, 9.x or all, doesn't matter), and the updated date
  • v
    the first publish doesn't matter (for docs)
  • v
    (and for me)
  • v
    it would be like, say, "Linux, Published on 25 august 1991, updated on 13 october 2026"
  • v
    (not sure I've got the right example though)
  • m
    yeah I agree, was thinking about the docs that have never been updated since we imported from 5.5, but just showing Last updated in 2012 is good enough
  • v
    that I'm not sure. docs from 2012 might still be relevant. say you did a bash tutorial in 2012 with a few basic concepts, that has not changed today.
  • v
    basic puppet language has not changed either... file { '/tmp/foobar': content => 'first file', } is still very much valid
  • v
    the indication that it /is/ still valid for openvox 9.x is important, though
  • v
    "that doc applies to puppet >= 4.x up to openvox 9.x"
  • v
    which means it will have to be touched when openvox 10 will be out, but nothing's perfect
  • v
    determining the freshness of a source, and even more to which versions you might use what's inside, is sometimes complicated
  • v
    who never pasted something in a search engine, got a 18 years stack overflow hit, which just has the correct answer ?
  • m
    I have this out there for group approval, github.com/OpenVoxProject/openvox-docs/issues/494 addresses a couple of those issues, but yes it's more complicated than you might guess.
  • v
    I bet
  • v
  • v
    that way it's explicit
  • v
    comments, or I push to PR as is ?
  • m
    open the PR, looks fine to me
  • v
    thanks
  • m
    I opened [Bug]: Report reference folds the http heading into the none section which caused doc publishing to fail. I have a workaround in github.com/OpenVoxProject/openvox-docs/pull/519 to unblock docs CI until the root cause can be fixed and tagged in new openvox release.