6pac
Migration of documents from wiki to the docs directory of the repository
Clear and concise description of the problem
I have checked the documentation related to this project and found the following two places
- https://github.com/6pac/SlickGrid/wiki
- https://slickgrid.net/
Although the wiki is excellent, others cannot modify it. The documentation should also be a part of contributing code, and those who want to contribute may translate the documentation into a language they are familiar with
As for the website slickgrid.net Opening it caused me to lose half of my interest in reading . It's really ugly, forgive me for being too direct . I have seen the repository and will migrate towards modernization, such as moving away from jQuery and adopting typescript behaviors Therefore, the document section should also be rewritten using some modern document tools .Finally, we only need to maintain it in one place, not in a wiki or slickgrid .If you agree to do so, perhaps I can help
Suggested solution
I am familiar with Vitepress and have helped many projects rewrite documents and migrate to Vitepress
The effect can be viewed vitepress
Alternative
No response
Additional context
No response
Validations
- [X] Follow our Code of Conduct
- [X] Read the Wikis.
- [X] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.
Sure go ahead, it's an open source maintained in our spare time and documentations is not where we typically spend our time (we always considered that all the Examples are the docs). Side note however, I've never used Vitepress and where would these docs be stored? Can that be uploaded to the GitHub Pages of the project? I don't have access to that part though, @6pac would have to update that part
Yes, everyone has their own work and life, The purpose of Vitepress is to reduce the time required for document maintenance, as you only need to maintain the markdown file. The markdown file can be stored in the docs directory of the repository. Yes, it can be deployed on GitHub Pages
@ajiho I'm just not sure on the advantqge of using a tool versus just having the docs in the GitHub wiki and perhaps making them editable (I actually thought they were - I think we can make them so).
Re the comments on slickgrid.net - yes you are right, it is ugly. I designed it, and I'm very much a backend guy. I've tried to make it look better several times but not succeeded. I think the best would be to merge it into the wiki and then forward from the domain.
The main reason we registered it was because the old original (now inactive) SlickGrid repo consistently appeared in search results above the live repo. I thought a domain was the best way of trying to escalate search ranking for the correct site. This is probably no longer an issue - we could post a single page notice to go to the repo, or page redirect, or perhaps just leave it to expire and remove the site altogether.
Yes, we can edit wikis, but only warehouse maintainers have the authority to update them . In open source, contributions should also work for documentation. Once the documentation is there, contributions to this documentation would follow the usual Pull Request pattern. Regarding slickgrid.net, once we use a tool to build documents, we can deploy it using GitHub pages or Vercel, and then bind the domain name. Perhaps a good project should have its own domain name, haha
As I mentioned earlier, doing so can also better support internationalization
@ajiho if you are happy to set something up, I'm happy to try it out. What we really need as well is to work on the content.
Just FYI my favourite documentation of all time is moment js - they use a cool little javascript lib to sync the content and detail points.
@ajiho are you still interested in doing this docs migration? I would say that we are both certainly welcome to the idea, so any PR for this change would be welcomed. Thanks
My 2 cents on documentation come from my experience as a "user", "buyer", and "developer" of other people's software (in that order). Before I was a developer, I always had to buy software. I still buy software now if I can't be bothered to develop it, or there is something so good or so crucial and I don't or can't spend the time at that moment to develop it myself.
I strongly prefer Free Open Source Software... FOSS with rights to reuse in my own commercial products without any payment to others other than attribution of source. Some people call this as "free" like "Free Beer" to use however you want without payment to anyone. Attribution is a minimal form of payment, an acknowledgement of origination other than yourself.
My rules for working with software are:
-
it is available as FOSS.
-
it fits my purpose and requirements. If Rule 1 is violated, I may use it for a while until I can find a FOSS version. I dropped LucidChart when I found Draw.io.)
-
it is well-documented, with usage examples, as many as possible to demonstrate utility.
-
the software is actively and well-maintained. (Unfortunately I had to drop QGrid when Quantopian folded.)
-
the documentation is well-maintained. I learned the hard way that FOSS products (or any product) without up-to-date documentation can result in extreme frustration. I eventually drop the product, sooner rather than later if the product is complicated. The more complicated a product is, the more important it is to have GOOD, UPDATED documentation.
Documentation is CRUCIAL part of product quality. I don't buy IKEA furniture anymore because I pay with my time every time I have to assemble their cheap products that have no written documentation in English (or any other language for that matter). They have only diagrams with cartoon dummies pointing with their cartoon fingers. Products without documentation in my language is an incomplete product. FOSS is not free; we always pay with our time.
Products without documentation are NOT COMPLETE. They are UNFINISHED. They may be HIGHLY functional, but still unusable.
The more complicated products are, the more unusable they are without good documentation.
Complex does not have to mean "complicated". Products can be complex and sophisticated, which means complexity is hidden from most users, but can be revealed progressively on demand.
If FOSS has no documentation, my first temptation is to walk away, unless it use is SO obvious that it does not need documentation. Now in the days of AI, I can ask Github to give me documentation. Usually the response is a usable starting, if I ask correctly (sometimes this takes a few tries, but often works. ) It still needs technical and writing expertise to make it GOOD documentation.
Bottom line. Documentation is crucial for making any product successful.
FWIW.
Hi @richlysakowski, I agree, I just don't have the weeks, possibly months of time it would take to do the documentation. Ag-Grid is a paid grid similar to Slickgrid and the guy who runs it says basically what you said - he doesn't regard a feature as done until it is fully documented.
Documentation is really hard and time consuming to do well - look at something like Telerik, who have been paid forever and charge a lot for their products. Their docco is almost incomprehensible. You have to piece together a solution for a vanilla use case from a series of KB articles using probably obsolete versions of the software. Microsoft is usually similar. Docco needs to have versioning built in at ground level. If it's not done well it is its own little disaster.
Slickgrid is essentially a toolkit - it's a bit like Unix - not for everyone, but rewarding if you put in the effort. We have tried to compensate for the lack of documentation with comprehensive examples.
@ghiscoding has much better documentation for the Slickgrid versions he maintains (slickgrid-react and slickgrid-universal).
What we need is for some talented and enthusiastic individual (like yourself??) with lots of spare time to come along and create this documentation, and probably a slick website too. Unfortunately, this seems to be a niche project which doesn't have an active enough community. But perhaps it's also chicken-and-egg, where if we got better docco more people might support us.
Unfortunately, at the moment proper docco is in the 'love to have, but a pipe dream' category.