@ornias Yes, you and anybody else that wants to help us convert the old-style guide to markdown would be more than appreciated, and we'd be happy to include it in the official docs / hugo site. We've been swamped lately with all the tasks around 12.0 launch, but would be happy to help sanitize / format the document if you get a pull-request opened. It would be good to list it in the
reference section of the new site, and once in markdown, it'll be easy to pull from to flesh out other parts of the site, or just link directly to in how-to style articles.
I do very much appreciate all the interest in this topic as well. Moving to a new-style docs system is no small task, and for the size of team we have working on it, we've made huge progress for 12. However, there is obviously more to do, screenshots to take, reference docs to port over. It's going to be some time to get all that done and finished to the state we want, but rest assured, it is happening.
Any cycles the community can help to make this go quicker will be much appreciated, and the new site / markdown format makes it virtually painless to help contribute content. If you can figure out how to use Xenforo and write forum HOWTO's, you can just as easily add content or a HOWTO on the official docs site. Making this as easy as possible was the goal, since our forum users tend to write awesome content, but it gets lost on the forums over time. We wanted to make sure this great content could just as easily live on over on the docs site, and allow others (iX included) to ensure it gets updated as the software evolves.
@Kris Moore - This is really welcome, and very constructive! Thanks!
Here are my thoughts how to make it a reality, given the timescale for it all. Which is probably under 3-4 weeks now.
I think we need to move fast, and this is roughly what I propose, if agreeable, to leverage the community and allow us to work fast, as IX wants, and without major issues arising. The aim would be, to get it "good enough for 12-REL".
First, I think it's *got* to be a joint effort. Not just "as a broad principle" or "you can contribute" (the usual things people say),
but because it can literally, only be achieved in a 12-REL timescale, by both community and IX working together as a collaborative focused project. There are things that people here can do, but some aspects of it that we badly need IX input, help, and guidance - and *not* via the slow "one item = one issue" method of Jira or Github.
Community members (self included) would be glad to help convert, update, refine, and review 11.3 docs, pull it to usable "docs hub" chunks, and PR it for v12 docs. I have no doubt of that, especially given the amazing offers to undertake and support the work by so many experienced users and fans. We can do it, and it'll speed IX work an order of magnitude, and free resources, and quite likely get 12-docs complete, on the hub, and ready in *some* form (even if not perfect! Enemy of good!) for 12-REL.
But to do that, we will surely need real help from IX too.
We can't afford to do it, only to find its all wrong in your eyes, or start over again. We cant afford long waits for replies to check if stuff looks broadly okay in approach, because so much needs checks beyond the technical wording. The technical wording is the smallest issue this time around (the 11.3 docs are already IX-scrutinised and we'll get most changes right where changes are needed). The big ones are things like - are the chunks we've broken stuff into okay? Are the topics roughly the right size? Are we striking the right notes? And that's before technical review of content itself.
So we will need need someone IX, or IX trusted, with part of their tasked role being "on the project team" who is our point contact, engaged with the effort, authorised to yesno what community members do, or want to check, so we can get it right quickly and surely, and who can make the decision to actually "sign off"/commit chunks as they are done, as "good enough for a first cut".
The technical review can probably be trusted to the community in the first instance. That's not usual, but probably justified for this one time (Perfect enemy of good!). Nobody inexperienced is going to do something like this. So trust us on the broad content (we can FIXME or CHECKME flag anything we aren't sure of to be dealt with in one go), and focus on information conversion and a decent "first go". We'll get it right enough for release, and with point-person help, we will also get sit formatted and styled professionally enough to pass. It can then be given a brief technical review for serious issues, as chunks are done - and we can polish anything else afterwards.
That's how I'd approach it, and I think it could work.
But the key needs are really needed, I think, if it's to stand a chance. Namely:
- Working together for real (joint project style) not just Jira/PR style. An informal ad-hoc project group of community folks, plus at least some modest hours daily by some IX person, or someone IX trusts to help and be our point-go-to person (see next item). Give us a forum thread or better a github docs branch we can freely work on/mangle, to discuss anything that needs answers or discussion.
- Allocate someone part time who is tasked with helping and given enough time (2 hrs a day maybe???) to quickly turn around our collaborative queries, and authorised to decide in the first instance queries on whether something's ok or how IX would want it. Their role is to (1) guide/help us be sure we write in a way that fits IX vision, (2) occasionally escalate and get answers from within IX on technical points that may occasionally come up, if we as volunteers can't figure it out, and (3) commit chunks to the hub if happy with them as we do them. Not really to do technical review.
- Having done that, trust us to get a first cut decent enough with their help/guidance/input, and flag most "non cosmetic" technical queries/factchecks, in other words bypassing the usual rigorous review of everything. Trusting we catch 98% of it and it's "good enough" for a first usable cut.
- And therefore, limit further IX review to a quick "skim read" technical review for "good but not necessarily perfect" and "nothing seriously wrong", once chunks are done (because your person on the team will have guided most of it already!) Just use it. Save further refinement for PRs and/or after 12-REL.
It'll be good enough, and fast. Can we have those few things? A group github docs branch (and forum thread perhaps), someone who can okay/commit/guide stuff with a couple of hours allocated a day at a guess, and a free hand to move fast and be trusted to autonomously get a first cut thats "good enough for now", without being held back by slowness inherent in usual processes.