wiki

[jonschlinkert]

@matthew-dean please add all documentation to the less-docs repo. We closed down the wiki due to confusion and to keep all efforts focused on one documentation resource.

Also, anything that is related to a plan, planning, milestones, etc. should be created as an issue wherever appropriate so that anyone in the community can discuss, and we can then create any requisite issues tied to necessary milestones and tasks.

[matthew-dean]

Hey, Jon. The issue is that there are a smattering of ready-to-implement features and sub-features that aren't documented in one place. I wasn't sure less-docs was the right place for it, because less-docs seems more for current documentation and not future feature documentation. Those features may evolve towards implementation (or not be implemented at all). So, really, it was a place more for contributors / developers (connected to the the less.js lib) then the public-facing information. I don't know that it makes sense to put that on the lesscss.org website, where it might confuse people as to what it means, but I'd welcome your thoughts about it.

My plan was just to give a list of various categories / sub-categories of features, list which ones are implemented and which version, and list features / sub-features, a page summarizing the feature (as the information on that feature can span a very long Github issue thread), and of course a link to the discussion. My goal was to summarize for easier "overview" digestion for collaborators and not to attach any plans or milestones, although that could certainly happen.

[jonschlinkert]

I'm convinced, that does sound like something that would be great for the wiki. or maybe just a repo dedicated to this, like roadmap, or planning or something. I guess it's arbitrary whether it's a repo or wiki, but if you my 2c I've found the wikis to be harder to work with. They seem more "mysterious" to use to newcomers because github doesn't have nearly as much as support for them and most people don't even know they have their own git urls. either way, yeah I'm on board with that. makes sense

[jonschlinkert]

thanks for the explaination

[matthew-dean]

No worries. Yeah, it's more of a "repo documentation" than "Less.js documentation". There were just some issues were people wanted explanations of features. We could point to the discussions, but people were kind of like "TL;DR". So the idea would be we could link to the summary.

Actually, making a separate repo is interesting. Hmm.... I have seen a project where that was the approach. But in my mind I was thinking of something like a single static view, and issues tend to order by activity or reverse chronological. I was actually thinking something like the W3C's "summary" page for CSS3 features. They had a single table for what was final, and what stages of drafts other features were in (and, of course, you could link to the spec for each one).

[jonschlinkert]

Yeah, IMO whatever works for you if you're the one stepping up to do it. Just a thought though, if you do a repo you get the full benefits of the issues, milestones, you can still "click and edit" from the UI like wikis, etc. I'm only pushing a little because I've gone full circle with wikis on github. I used to wiki quite a bit, and it's just easier in my workflows to maintain a repo than a wiki. plus if it's a repo it's easier to store things like images or graphics that might be used in any docs - and you can render the docs to HTML in gh-pages easily etc. just my 2c though, like I said whatever works for you.

They had a single table for what was final, and what stages of drafts other features were in (and, of course, you could link to the spec for each one).

I love that kind of stuff. If you haven't noticed in my projects, I'm somewhat of a documentation freak (although I probably like making tools to generate documentation more than actually writing the documentation). to your point about the w3c stuff and links to specs, take a look at https://github.com/jonschlinkert/arr, click on any of the headings / method names. Just to show that this is possible, and perhaps just as easy (and in my workflow, easier) to automatically generate relative links to other documents even on actual repos. the tool I use can even generate a multi-page table of contents with relative links. Or to add a toc to any page, just add a code comment, like:

<!--- toc --->

That way if the toc doesn't render, no one even sees the code. Keep in mind that wikis won't warn you when you do [[foo]] and later change the name of the foo page to bar. You now have a broken link that won't fix itself until you find it or someone creates an issue.

sorry I'm probably complicating this for you lol. but this is something I really enjoy doing - the actual documentation generation part.

[matthew-dean]

Ohhh... wait, are you saying like storing the documentation html in a repo? Maaaybe, but seriously I want to keep it simple. Like literally a table with links to spec summaries. I thought you were saying start a new repo and document via the issues.

Also: I didn't know you could link to code like that. Cool! That would be good for documenting the less.js code itself!

[jonschlinkert]

html? no, I would use markdown, like maybe just a README.

ike literally a table with links to spec summaries. I thought you were saying start a new repo and document via the issues.

yeah, that's what I mean. You can use html code comments in markdown too, if that's what you're referring to. Just to show how serious I am about markdown ;-), https://github.com/jonschlinkert/remarkable. We'll be releasing remarkable in the next couple of weeks. It's passing - and will pass - all stmd specs/unit tests. It will be the markdown renderer to beat.

[jonschlinkert]

wait, to clarify, I meant... start a new repo and use the readme and or any other markdown files you need, for whatever purpose, and you also have the benefit of being able to use the issues for related discussions, while freely and clearly linking to the resources in the repo. again, IMHO wikis are burried and hard to find on github, and you'll probably be more conservative in your approach to creating/linking related issues on the main less.js repo than you would be if you had a repo dedicated to what you want to accomplish.

[lukeapage]

How about a roadmap page (or futures or something else) on the website?

[matthew-dean]

@lukeapage I'm not against that. What if I did this: start a new repo ("less_roadmap"?), using .md files to lay out the condensed features table and summarize ready-to-implement features (linked to the appropriate less.js discussion thread). Then we can use the Github issues for less_roadmap to figure out priorities / version targets? That way less.js issues could be more bug focused.

Then, if we had something like a "production plan" we wanted to move to the website, we could easily do so. I just didn't want to push something to the web documentation prematurely, as I haven't even gone through issues yet and done the archeological work.

Cool?

[matthew-dean]

@lukeapage Maybe this could also be a way to document segments of code / API (addressing issues like #212) the way that @jonschlinkert demonstrated with code linking?