Page 1 of 1

Outdated documentation

Posted: Sun May 22, 2022 3:32 am
by cephstore
The official documentation online seems to be missing quite a few features and seems to be lagging behind the code in a not so insignificant amount.

I submitted a few patches to update the documentation but they have not been accepted.

Re: Outdated documentation

Posted: Sun May 22, 2022 3:42 am
by michael
The patches you submitted were not accepted because they were a copy of the text and images from the book and other online sources.

We can only accept original content.

We replied to the patches with a more detailed explanation.

Re: Outdated documentation

Posted: Sun May 22, 2022 3:47 am
by cephstore
The book is outdated and no longer being sold, by default it is now public domain. The "other" content came from blog posts and had no copyright notices.

Re: Outdated documentation

Posted: Sun May 22, 2022 3:54 am
by michael
The book is outdated and no longer being sold, by default it is now public domain.
In general, for works created on or after January 1, 1978, the term of copyright is the life of the
author plus seventy years after the author’s death.
https://www.copyright.gov/circs/circ01.pdf

Summary: The book is still copyrighted.
The "other" content came from blog posts and had no copyright notices.
When is my work protected?

Your work is under copyright protection the moment it is created and fixed in a tangible form that it is perceptible either directly or with the aid of a machine or device.

Do I have to register with your office to be protected?

No. In general, registration is voluntary. Copyright exists from the moment the work is created. You will have to register, however, if you wish to bring a lawsuit for infringement of a U.S. work. See Circular 1, Copyright Basics, section “Copyright Registration.”
https://www.copyright.gov/help/faq/faq-general.html

Summary: Anything published is automatically copyrighted even if there is no copyright notice.

Re: Outdated documentation

Posted: Tue May 24, 2022 12:05 am
by cephstore
What then is the solution to up-to-date documentation? Documentation is crucial for onboarding our users. And keeping incomplete and old stuff make is more confusing. Why not remove the documentation and make the book the canonical documentation? There is in nothing in open source that says that you can never charge money for something, it's all about license.

Re: Outdated documentation

Posted: Tue May 24, 2022 5:39 am
by franco
What then is the solution to up-to-date documentation?
Submit patches improving it that is not a copy/paste of copyrighted material.
Documentation is crucial for onboarding our users. And keeping incomplete and old stuff make is more confusing.
You can subscribe to any of the support plans or get a quote for a custom contract that includes on-boarding. There are multiple options.
Why not remove the documentation and make the book the canonical documentation? There is in nothing in open source that says that you can never charge money for something, it's all about license.
The first thing you've said I fully agree with.

This is what almost every mayor software companies and even hardware manufacturers are doing. The best you get now after a three grand laptop purchase is a paper insert with IKEA style drawings telling you how to get it out of the package and plug it into a wall socket.

Re: Outdated documentation

Posted: Thu Jun 02, 2022 3:18 pm
by mroy
Is there anywhere I can buy the book? I agree that the documentation seems lacking, but I've heard great things about the book. I'm happy to pay for it, but it is listed on the website as out of stock. How can a PDF be out of stock?

Re: Outdated documentation

Posted: Fri Jun 03, 2022 5:17 am
by dansumaar
Hi there. Long time user and forum creeper.

I bought the book while evaluating Mayan for work and now that it has been rolled out to production I find myself needing more copies for our users. I want to comply with copyrights and support the project by buying more copies.

I understand and appreciate the reasons for discontinuing sales of the book. The installation section has changes but I would say that 90% of the concepts the book are still applicable. The other area that changed is the API but Mayan has live API documentation so it is not a big deal. I've seen in some posts that there are people still using version 3 family of Mayan. I propose adding a note to the sales page that the book is outdated but not obsolete.

I also agree with reducing the online documentation and making the book the primary source of information. I have to write a lot of technical documentation for my work and it is very exhausting and intensive work. Almost as much as writing code. Diagrams are especially hard and time consuming, and get obsolete very quickly as opposed to written text.

My last recommendation is to no try to make a new book for each release. Instead do a rolling release in the form of editions that add, update or remove old content. Makes it easier to put out a new book for each or every other release of Mayan. This is a normal practice with tech books and even university books. If there are people that complain about having to buy the new edition, do a sales event, or a coupon for previous buyers, or an early bird special. I speak for myself but I'm certain that users that want to support the project will not mind paying full price.

There isn't anything out there that compares to Mayan. It is very important to support this project and help keep it alive. Buying a book is a small price to pay for all the time and money savings we get in exchange.

Re: Outdated documentation

Posted: Mon Jun 06, 2022 6:21 pm
by mroy
Thanks to Roberto the book is now available again for purchase on the website.
I bought my copy this morning. Happy to support the project.

Best Regards,

Mark