@Moult said:
In the present, we already do a lot that is either IFC pioneering (constraints in parametric 4d and 5d), or stretching the IFC definition (drawings, annotations), or completely not native IFC (stair, railings, sverchok, CSS). The fact that some people didn't realize this was the case is awesome, but perhaps scary too.
This is looping back around to the lack of up-to-date, complete documentation and tutorials. It's all well and good that tools are improved and features added, but if people don't know about, or how to effectively use them, it slows uptake. Unfortunately, high churn leads to a disincentive to spend a lot of time on these aspects.
I was thinking about contributing to the Drawing and documents page, but a) I'm not sure I know enough, and b) The http://docs-unstable.bonsaibim.org/reference/properties.html page does not have appropriate links to the property pages, some of which have a lot of useful, but possibly out-of-date information. I can't decide if they are deliberately not linked because of UI churn, or if linking them was just overlooked.
(Apologies for the rather off topic comment.)
They were deliberately not linked. A bunch of docs were written, but quickly made incomplete or out of date, and although this is contentious, for official docs I prefer less docs but maintained and trustworthy vs more docs but patchy.
The lack of docs is unfortunate but just the reality. Five years into the project, the basics are still changing. Part of me feel guilty on how this dragged on so long, but part of me also knows we've done our best. I genuinely believe we are in an alpha-to-beta transition phase, which means that the basics are actually stablising. Things like the polyline and snap, wall layers, shape aspects, item editing, feature elements, all coming together in a cohesive experience that I'm starting to be proud to say "This. This is how IFC modeling works. And it's exactly what you're used to".
But enough excuses. If someone wants to take control over the docs, please let me know. I'll be more than happy to demonstrate which parts I believe are stable, and which aren't. How do you write docs about "Here's how you draw a wall" knowing that the polyline tool literally just changed everything again? Even right now, many of the existing images in the docs aren't up to date, and it takes a very long time to go through and redo them. Maintaining docs takes time, especially with the image heavy experience I'm hoping for. @vanuan did a great job inspiring what pages could be, but I (and maybe it was the wrong move) quickly censored the pages again after I realised most were skeletal (again, my "less is more" bias) or about to change completely.
I also apologize for the comment that is also off topic.
I think that creating visually beautiful and "step-by-step" documentation like the one that is being done is a waste of unnecessary energy. In times of AI...
As a user who doesn't have much time or patience to look for where things are in extensive documentation, I think that an official Bonsai channel on YouTube with short and objective video tutorials (like the ones @theoryshaw and others make to answer users' questions here on the forum) would perhaps be more efficient, easier to maintain and could be monetized to raise funds for development.
E.G:
Title: BLENDER BONSAI BIM - How to ...
Content:
standardized introduction with logos and warning about the version that was used
demonstration of one tool at a time (with audio describing the "step-by-step", without music or other complexities)
standardized ending with a list of useful links
If this is a stupid or unfeasible idea, please ignore me... :)
Coincidently, since daddy is still low on work, I've started to make a series of paid-for video tutorials. I'm starting from learning vanilla blender, and will go obviously into Bonsai. https://hub.openingdesign.com/OpeningDesign/Bonsai_Tutorials
It would be cool to create a system where anyone can add to these tutorials, and in turn receive fair revenue for their contribution.
How do we determine what is fair? I don't know, but i bet we can hack something.
And yes, I think it important to direct a percentage of this revenue toward Bonsai development.
At the end of the day, we all have to eat.
@Moult said:
The lack of docs is unfortunate but just the reality. Five years into the project, the basics are still changing. Part of me feel guilty on how this dragged on so long, but part of me also knows we've done our best.
Don't ever feel bad about it, you guys are doing amazing work. Writing good documentation is a huge time sink, often as much if not more than coding the corresponding features.
We can live without documentation, but we can't without the features. I'd consider it a waste to have developers waste too much time into docs that could be used for actual coding, considering how thin you are stretched. Docs are also something the community can easily help with, at least the less technical end user documentation.
I've actually been meaning to ask if one could get commit permissions, or some sort of review and approval system set up so we could contribute in that regard. I have some experience writing answers in the Blender Stack Exchange sites, that I like to illustrate with lots of images and gifs for the processes, which I think would lend itself to the "image heavy" documentation Dion was aiming for.
I won't pretend to know enough about Bonsai or BIM in general to help at this point, and it will certainly take some time until I could be of any actual use, but I'd certainly like to be involved at some point.
@walpa said:
As a user who doesn't have much time or patience to look for where things are in extensive documentation, I think that an official Bonsai channel on YouTube with short and objective video tutorials (like the ones @theoryshaw and others make to answer users' questions here on the forum) would perhaps be more efficient, easier to maintain and could be monetized to raise funds for development.
I sit at the opposite end of this, I abhor Youtube tutorials. All the unskippable ads, loud verbose intros "Hello and welcome!!!" "please like and subscribe", "a word from our sponsors", being unable to easily skip to the specific part that you need or find that particular step you missed.
They are also very hard to maintain in the long run, especially for rapidly changing software, because when they get outdated, they are hard if not impossible to update. You can't easily go in and alter a part of a video because some part of the workflow changed in recent versions, and that generally means an entirely new video, unlike written docs, which you can go in and change a bunch of paragraphs or an image and the rest still holds together.
And yet, I can certainly see that videos have their advantages.
I don't think there is enough audience yet that they could be meaningfully monetized, but if there ever is, it would certainly be appealing and encouraging creators.
It also has a lot higher visibility, it is a very popular format these days, and may very well act as a marketing technique, while playing its documentation role. I first knew about Bonsai from one of UH Studio Design Academy videos about then BlenderBIM
Contributing the docs with commit permissions / review is exactly the same process as writing code. Simply submit a PR, it will get reviewed, and then merged. If you are a regular contributor where reviewing is not necessary, you get full commit rights.
If you want to have a video call to go over what you had in mind for docs and what I believe is worth documenting (don't want to waste time on something that is going to change soon) let me know :)
We need both official docs and unofficial docs. We need all types of styles: text-guidebook style, video tutorial style, and "reference-lookup" style docs because different styles resonate with different people. My current minimum standards for docs are:
There must be a tutorial style straight-into-it howto explaining how to check out a model in 10 minutes.
There must be a tutorial style howto explaining creating your first (tiny) model with a few objects in 20 minutes. Put together, if you're a fast reader, in half an hour to an hour, you've got the most used functions understood. You should understand types, spatial containers.
There should be a reference/dictionary-style explanation of every interface methodically (similar to upstream Blender docs). Starting with overall interface, then methodically going through every panel.
There should be some guidebook style documents on commonly asked usecases like so. There are more that should exist, like modeling.
There should be beginning-to-end designing a small house including arch, struct, mep, time, cost. (none of this exists yet for obvious reasons)
@Moult said:
If you want to have a video call to go over what you had in mind for docs and what I believe is worth documenting (don't want to waste time on something that is going to change soon) let me know :)
Will do. I don't know enough at the moment to feel comfortable writing documentation, probably wont for a while, but I'll let you know when I do.
I don't think I'd be the adequate person for video tutorials, but I'd certainly like to help with written ones.
One method that might help establish good written documentation is to type down what I learn as I go, mirroring what I would have liked to find in the official documentation. I might make a small sample beforehand and post it here to establish style and structure.
@duarteframos Another solution which you may find easier, and as you have some experience ;) over on BSE, is to leverage StackExchange's Q&A style to add and maintain some form of documentation for specific problems. EG a Q&A for how to draw a wall, how to add a window, how to add an opening, etc. BSE has a lot of shortcomings, but the main advantages : no bullshit, cut to the chase, bullseye specific questions and answers ; a user-based democratic voting to weed out bad content ; questions can be edited, as well as answers, and there is no limit to the number of answers. Contrary to a video tutorial if the specific feature or UI changes every few months, the answers can be edited seamlessly to stay up to date, retaining the whole edition history.
Only 2 problems I see now is that there are not a lot of Bonsai users over there, so content would be driven by only a handful of people, but to be fair it's already the case for pretty much everything out there. There are from time to time people asking about Bonsai - BlenderBIM so google search results tend to push people over there. And Stack Overflow is a private company and as a whole has made some very questionable decisions over the years.
A Stack Exchange step based style documentation was actually what I was aiming at for the documentation, because I find it very easy to follow.
Something along the lines of
How to create a wall/slab/opening/roof
1. Click toolbar button
2. Open relevant settings in top bar
3. Create a new type
4. Press some Key
5. Draw something
5. Click to finish
A stack style Q&A format would be great to, I love the tiny videos @steverugi leaves here and there scattered around the forum, they are very informative, but I fear they may some times be lost to time, and lack the data structure to support them.
A well tagged, searchable Q&A format would be a much more honorable place for them, but as you say, SE is not a company I'd like to support any further, and it'd be a shame to start building our metaphorical castle on their land.
I wonder if there is any open source, self-hostable stack-exchange-like web software we could use for this purpose.
Edit: I found Apache Answer https://answer.apache.org/
@JanF said:
What's the benefit over using the wiki we already have?
There is place for both, I think they cover different scenarios.
The wiki is great for official documentation, but a wiki can only document so much. It is also unable to cover every particular use-case and every single different corner case without becoming overwhelming.
The Q&A is more suitable for practical examples, common pitfalls, different approaches to the same problem, and direct questions from users. It is also less static, more like a community effort which fosters engagement with voting and comments. Downsides being it needs heavy moderation to be of any actual use.
Comments
This is looping back around to the lack of up-to-date, complete documentation and tutorials. It's all well and good that tools are improved and features added, but if people don't know about, or how to effectively use them, it slows uptake. Unfortunately, high churn leads to a disincentive to spend a lot of time on these aspects.
I was thinking about contributing to the Drawing and documents page, but a) I'm not sure I know enough, and b) The http://docs-unstable.bonsaibim.org/reference/properties.html page does not have appropriate links to the property pages, some of which have a lot of useful, but possibly out-of-date information. I can't decide if they are deliberately not linked because of UI churn, or if linking them was just overlooked.
(Apologies for the rather off topic comment.)
They were deliberately not linked. A bunch of docs were written, but quickly made incomplete or out of date, and although this is contentious, for official docs I prefer less docs but maintained and trustworthy vs more docs but patchy.
The lack of docs is unfortunate but just the reality. Five years into the project, the basics are still changing. Part of me feel guilty on how this dragged on so long, but part of me also knows we've done our best. I genuinely believe we are in an alpha-to-beta transition phase, which means that the basics are actually stablising. Things like the polyline and snap, wall layers, shape aspects, item editing, feature elements, all coming together in a cohesive experience that I'm starting to be proud to say "This. This is how IFC modeling works. And it's exactly what you're used to".
But enough excuses. If someone wants to take control over the docs, please let me know. I'll be more than happy to demonstrate which parts I believe are stable, and which aren't. How do you write docs about "Here's how you draw a wall" knowing that the polyline tool literally just changed everything again? Even right now, many of the existing images in the docs aren't up to date, and it takes a very long time to go through and redo them. Maintaining docs takes time, especially with the image heavy experience I'm hoping for. @vanuan did a great job inspiring what pages could be, but I (and maybe it was the wrong move) quickly censored the pages again after I realised most were skeletal (again, my "less is more" bias) or about to change completely.
I also apologize for the comment that is also off topic.
I think that creating visually beautiful and "step-by-step" documentation like the one that is being done is a waste of unnecessary energy. In times of AI...
As a user who doesn't have much time or patience to look for where things are in extensive documentation, I think that an official Bonsai channel on YouTube with short and objective video tutorials (like the ones @theoryshaw and others make to answer users' questions here on the forum) would perhaps be more efficient, easier to maintain and could be monetized to raise funds for development.
E.G:
Title: BLENDER BONSAI BIM - How to ...
Content:
If this is a stupid or unfeasible idea, please ignore me... :)
Coincidently, since daddy is still low on work, I've started to make a series of paid-for video tutorials. I'm starting from learning vanilla blender, and will go obviously into Bonsai.
https://hub.openingdesign.com/OpeningDesign/Bonsai_Tutorials
It would be cool to create a system where anyone can add to these tutorials, and in turn receive fair revenue for their contribution.
How do we determine what is fair? I don't know, but i bet we can hack something.
And yes, I think it important to direct a percentage of this revenue toward Bonsai development.
At the end of the day, we all have to eat.
Don't ever feel bad about it, you guys are doing amazing work. Writing good documentation is a huge time sink, often as much if not more than coding the corresponding features.
We can live without documentation, but we can't without the features. I'd consider it a waste to have developers waste too much time into docs that could be used for actual coding, considering how thin you are stretched. Docs are also something the community can easily help with, at least the less technical end user documentation.
I've actually been meaning to ask if one could get commit permissions, or some sort of review and approval system set up so we could contribute in that regard. I have some experience writing answers in the Blender Stack Exchange sites, that I like to illustrate with lots of images and gifs for the processes, which I think would lend itself to the "image heavy" documentation Dion was aiming for.
I won't pretend to know enough about Bonsai or BIM in general to help at this point, and it will certainly take some time until I could be of any actual use, but I'd certainly like to be involved at some point.
I sit at the opposite end of this, I abhor Youtube tutorials. All the unskippable ads, loud verbose intros "Hello and welcome!!!" "please like and subscribe", "a word from our sponsors", being unable to easily skip to the specific part that you need or find that particular step you missed.
They are also very hard to maintain in the long run, especially for rapidly changing software, because when they get outdated, they are hard if not impossible to update. You can't easily go in and alter a part of a video because some part of the workflow changed in recent versions, and that generally means an entirely new video, unlike written docs, which you can go in and change a bunch of paragraphs or an image and the rest still holds together.
And yet, I can certainly see that videos have their advantages.
I don't think there is enough audience yet that they could be meaningfully monetized, but if there ever is, it would certainly be appealing and encouraging creators.
It also has a lot higher visibility, it is a very popular format these days, and may very well act as a marketing technique, while playing its documentation role. I first knew about Bonsai from one of UH Studio Design Academy videos about then BlenderBIM
Contributing the docs with commit permissions / review is exactly the same process as writing code. Simply submit a PR, it will get reviewed, and then merged. If you are a regular contributor where reviewing is not necessary, you get full commit rights.
If you want to have a video call to go over what you had in mind for docs and what I believe is worth documenting (don't want to waste time on something that is going to change soon) let me know :)
We need both official docs and unofficial docs. We need all types of styles: text-guidebook style, video tutorial style, and "reference-lookup" style docs because different styles resonate with different people. My current minimum standards for docs are:
Will do. I don't know enough at the moment to feel comfortable writing documentation, probably wont for a while, but I'll let you know when I do.
I don't think I'd be the adequate person for video tutorials, but I'd certainly like to help with written ones.
One method that might help establish good written documentation is to type down what I learn as I go, mirroring what I would have liked to find in the official documentation. I might make a small sample beforehand and post it here to establish style and structure.
@duarteframos Another solution which you may find easier, and as you have some experience ;) over on BSE, is to leverage StackExchange's Q&A style to add and maintain some form of documentation for specific problems. EG a Q&A for how to draw a wall, how to add a window, how to add an opening, etc. BSE has a lot of shortcomings, but the main advantages : no bullshit, cut to the chase, bullseye specific questions and answers ; a user-based democratic voting to weed out bad content ; questions can be edited, as well as answers, and there is no limit to the number of answers. Contrary to a video tutorial if the specific feature or UI changes every few months, the answers can be edited seamlessly to stay up to date, retaining the whole edition history.
Only 2 problems I see now is that there are not a lot of Bonsai users over there, so content would be driven by only a handful of people, but to be fair it's already the case for pretty much everything out there. There are from time to time people asking about Bonsai - BlenderBIM so google search results tend to push people over there. And Stack Overflow is a private company and as a whole has made some very questionable decisions over the years.
Cheers
A Stack Exchange step based style documentation was actually what I was aiming at for the documentation, because I find it very easy to follow.
Something along the lines of
A stack style Q&A format would be great to, I love the tiny videos @steverugi leaves here and there scattered around the forum, they are very informative, but I fear they may some times be lost to time, and lack the data structure to support them.
A well tagged, searchable Q&A format would be a much more honorable place for them, but as you say, SE is not a company I'd like to support any further, and it'd be a shame to start building our metaphorical castle on their land.
I wonder if there is any open source, self-hostable stack-exchange-like web software we could use for this purpose.
Edit: I found Apache Answer https://answer.apache.org/
What's the benefit over using the wiki we already have?
https://wiki.osarch.org/index.php?title=BlenderBIM_Add-on/BlenderBIM_Add-on_FAQ
There is place for both, I think they cover different scenarios.
The wiki is great for official documentation, but a wiki can only document so much. It is also unable to cover every particular use-case and every single different corner case without becoming overwhelming.
The Q&A is more suitable for practical examples, common pitfalls, different approaches to the same problem, and direct questions from users. It is also less static, more like a community effort which fosters engagement with voting and comments. Downsides being it needs heavy moderation to be of any actual use.