Freeplane hosts its own wiki at http://www.freeplane.org/wiki/index.php/Main_Page . (It is hosted by source forge servers in the project web space where no https support is possible yet). So if anyone wants to contribute to it just register and let us know your user names.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
The problem with the current wiki is not only that it is feature centric - as Peter said - but it is also badly organized, so you can't read through all the pages that are relevant to you in a sensible order.
I'm afraid that this problem will not simply be fixed by more people but by more planning.
For the past several years I've been working within teams separated by distance and time, sometimes as many as 12 collaborators in as many time zones. I've come to value digital collaboration as a very powerful way to get things done. These teams have been tasked with the development of large, comprehensive plans that define the long-term scope of complex projects over 3-5 years.
Freeplane, in it's current configuration, isn't well suited to collaborative tasks. It's a great personal tool, but awkward in collecting and processing collective thought. So a different tool seems to be needed, at least for the development parts. Wikis in their pure form were made for this, allowing many people to submit material and have them peer reviewed and revised before publishing. I'm not sure SourceForge's implementation is that robust, so perhaps somebody can enlighten. I have a great deal of experience with Google Docs. All the detractions aside, it is the only tool I've found that allows multiple people to work together in an efficient and controlled manner. Add a common language and phone or Skype connection and it's VERY powerful--like holding a meeting where each party can participate while seeing in real time what other collaboraters have added or commented about.
But with that said, I must also say that I've never seen a successful collaboration done without somebody that projects a vision of the end product. This person is really the team's chief editor and is empowered and acknowledged by each member on the team with the ability to arbitrate and, if necessary, ajudicate disputes. Dimitry and you play this role on Freeplane's technical side. This person would establish the vision of how the document will look in its final form and how various subcomponents ("chapters?") would fit together. They would manage a team of volunteer writers, assigning them appropriate tasks, very much like a project manager, with scope of work descriptions and due dates.
So, I'm in agreement with you 100%. What is needed, IMHO, is an individual that is well respected in the community and in whom all have confidence that they have the best view of what the final product should look like. This person would act as project manager, holding both individuals and the team as a whole to account for specific action items and "deliverables." Then we set up the appropriate technical mechanism that will allow people to take a piece for which they have knowledge and insight, draft up an initial submission for review and comment by the appropriate sub-team. Once the subteam is happy with their draft document, the whole thing is submitted to the larger team for review and suggestions.
Once fully vetted, the document could then be "published" to the larger Freeplane community.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
The person you describe sounds like you -- although I have a strong suspicion you would not put yourself forward. I think you would be excellent filling the job description you outline. You certainly have experience with collaborative projects. You've always struck me a extremely positive + you have more of a user-focus than a techie-obsession - although I've long considered you to be a FP master. And more than willing to listen to others.
I nominate Quinbus to spearhead this project, if he has the time to spare and is willing.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I think that this project offers a lot of non technical creative challenging and tasks and I agree with you that these tasks have basically not been systematically addressed yet. It would be great if a team came together for it. I think a good working team has much more power, capacity, stability, ideas, momentum and motivation than single persons.
I think it can be helpful to have a clearly defined vision and a derived task pool. Contributors could take tasks from the pool, and add their own tasks and also contribute to the development of the vision.
Personally I do not think that tasks should be assigned. Their motivation to contribute and satisfaction come out of inner conviction to do the right thing and out of the freedom to decide when they do it and not to do anything one doesn't like.
How do you see it?
Last edit: Dimitry Polivaev 2016-08-10
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I think it can be helpful to have a clearly defined vision
I'd like to volunteer to be on the team.
Do you envision the basic decision of mindmap vs document/wiki to come out of the team?
Or do you see that decision coming from the forum, either in this thread or another? Or something else?
I think that needs to be one of the basic decisions before getting too far into things. It would be a time waster to write blocks of text and then decide a mindmap would be better. The other way around would not be as bad, since a mindmap could serve as the outline for a blocky document.
I do not think that tasks should be assigned.
I agree. For example, there is plenty I don't know about FP so assigning me such a feature might not be a good idea, although it might force me to dig in and learn (assuming I make the team).
Last edit: Ken Hill 2016-08-10
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Ken, currently you are the only non-technical team member. So I thank you for that. I wish the team gets other people soon.
I think that all decisions are taken by people who do the work. And they should be taken so that no team member feels bad about them. All opinions coming from the outside e.g. from the forum only help the team to consider different ideas, views and arguments.
I think that in order to challenge someone to try something new and to dig in you can suggest to take a task without assigning it. You can help the other guy to believe in himself, support him and see him grow not by law and order, just by putting your trust in his judgement, competence and good will.
Last edit: Dimitry Polivaev 2016-08-10
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
The concept of "assignment" is a little harsh. I should have softened that a little. This is sitll a volunteer effort and there simply isn't any leverage to force somebody to do something that they don't want to do.
But speaking personally, I find it very hard to volunteer without a structure in place to know where to jump in. This is a litte bit "chicken and egg." Without some sort of framework, we each make interpretations about what we would like to see, some of which the community will support wholeheartedly and some which will have differing levels of support. Some of the proposals currently floated are counter to each other in direction (e.g., linear text vs. wiki vs. mindmap-based).
When you chose to fork Freemind, there were those in the old community that didn't see the benefit of restructing the code for future development. But you and Volker had a vision that has lead to a whole new user community who want to share what you initially saw. We need somebody with that confidence and vision for the documentation interface.
Lots of us ask you and Volker for what we think will be technical improvements. Your combined knowledge of coding, of the API and your vision for the product balanced with overall performance carries a lot of weight when you support, prioritize and sometimes gently decline. We need somebody like you on the documentation side that commands the same level of respect and offers practical ideas, questions and direction.
They don't have to do all the work. They don't have to drive anybody. But they need to have a vision (coupled, hopefully, with practical experience in writing user documentation) that others can grasp. I think there are many of us in the non-technical side that could/would contribute, but we need some sort of structure that is breakable into manageable chunks and priorities set in a way that each volunteer can see how their piece fits with a larger whole. Otherwise we're just all flopping aorund with the many different ideas of how to approach the task.
Q!
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
very hard to volunteer without a structure in place to know where to jump in
I'm with Quinbus - that it is a bit scary to volunteer for something that is fuzzy and nebulous.
linear text vs. wiki vs. mindmap-based
I still think some of these questions about very basic decisions would benefit by a survey or poll at some point. Otherwise, how do we get to a workable consensus in order to begin?
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I know there are different kinds of organizations, and I am confident that the one you choose together can work for you best.
I can however share some of my experiences.
In freeplane software development Volker, Felix and me usually discuss all decisions with high impact together whenever any of us wants it and reach an agreement. We choose our next tasks ourselves. People who want to try out new things get their space to try and get the support the rest of they team can give them. Attempts which do not work are sorted out.
At the place where I daily work I am a part of one sofware development team consisting of 7 members. We have agreed on a principle "together we find the best solution". We do not have formal hierarchies at this level. We have practices, processes and game rules. In our regular retrospectives we discuss our processes and rules and change them on a base of agreement. And we also have separate product owner and product managers who are in touch with customers. They decide what should be done next and they have no influence on the details of technical solutions we develop in team.
Anyway I would like to disappear from this discussion for a while so that I do not disturb you finding together and doing your first steps together. I am not a part of documentation development.I can not decide with you how you want to work together and which priorities you set. I just want you to be successful as a team.
Best regards,
Dimirty
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
In freeplane software development Volker, Felix and me usually discuss all decisions with high impact together whenever any of us wants it and reach an agreement. We choose our next tasks ourselves. People who want to try out new things get their space to try and get the support the rest of they team can give them. Attempts which do not work are sorted out.
This is the way it works, actually. But Freeplane's software was initially formed via a big rework of the basis of FreeMind. You had a vision and invested much more work than we others, so the strengths of Freeplane's architecture is much more the result of one mind than of discussions.
I think the documentation needs the same treatment that FreeMind's sources received mainly by you. And I think that Quinbus is right on how this could work.
By the way: I also believe that the software needs some improvement to improve the ease of use. Just improving the documentation is not enough.
I would be interested in Peter's opinion about this issue.
But Freeplane's software was initially formed via a big rework of the basis of FreeMind. You had a vision and invested much more work than we others, so the strengths of Freeplane's architecture is much more the result of one mind than of discussions.
Volker, current freeplane architecture has not only strengths. If I could discuss it with you during the redesign phase 2007 and decide together it could probably prevent us from some mistakes. I was working alone and now I doubt it was the most effective way.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Thanks for that peek behind the curtain. I found it very interesting and insightful.
One thing - as users, we do not see the marvelous things you do in the innerworkings of Freeplane - we only see the user interface.
With documentation, what the reader sees is completely on the surface. I agree that everyone on the documentation team should have lots of freedom and flexibility. But documentation with wildly different writing styles could end up being disjointed and even confusing. This would not be as much of an issue with a mindmap, where keywords are valued, but in a full-blown linear user manual it could be an issue.
One the other hand, based on my own experience, users might be expected to only look at one section at a time so writing style differences may not be noticeable.
And this forum has a lot of users from different nationalities and cultures, as well as a wide range of technical expertise, which could contribute to different writing styles.
At some point, the documentation team -- or perhaps a different team, not so close to the sometimes-emotional writing process -- should be tasked with making a pass thru the documentation trying to bring together style consistency. Especially for a linear manual.
I don't want to over-complicate this project. I bring this up to add this to the mix of considerations. It certainly is not an insurrmountable problem.
Documentation team members should be aware that their contributions are needed and valued - but their words may need to be edited. That should be out in the open from the beginning.
I've worked on other writing projects with people who thought their writing was perfect, and don't you dare touch one word! From my experience on the forum, I don't think that extreme will be a problem. This forum is very civilized and polite and positive.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
In my opinion, there is a lot of content already available in the current Tutorial map and also in the Documentation map. Why not use what has already been done and reorganize, structure it differently?
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
You're referencing the map that user Jodi created a few years ago? Do others remember that significant project?
This particular user tirelessly worked on making a comprehensive map of Freeplane's features. The thing was comprehensive and well thought through. Are we talking about something different than the use case Jodi's map was trying to address?
There may be a problem in here that unlike the software folks, we have no standard that defines what we're trying to build. If we don't take the necessary time to set a specification, we're just going to continue to chew up resources in various forms that only address some needs and leave others unmet.
As a user, it seems to me that the user interface is pretty confusing. There's the wiki, there are various maps, there is the program itself, there is the community fora on SourceForge (which replaced a BBS before), untold numbers of videos about the product. Where do we want to drive new folks for answers? Where is the place where all materials and guides points to? We pretty much now expect new users to just stumble around and find the answers they need whereever they can find them.
Maybe it's just me, but the problem doesn't seem to be "user documentation." It's the whole front office package that needs to be structured/restructured so as to enhance the experience for people like our recently inflamed poster.
It's a big job. Really big.
Q!
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I don't know Jodi and what map he created. There are 2 maps as a biginner user I initialy started to consult: Main Menu > Help
Documentation
Tutorial
DOCUMENTATION map is what I use to learn about the various comands in Freeplane. It is extensive and a good reference for in depth understanding of all commands. I would not scrap it, but restructure and mainly focus on the reference part of the map.
TUTORIAL is what I "REALLY" used as a biginner to understand what I can do with a mindmapping software and I think it is pretty well done and straight forward in the approach. There are three sections: Beginner, Advanced, Professional.
If I must add to that also the various videos on Youtube (including yours and Jonas lately) "Great job to both by the way!"
There are probably some corrections to make:
Maybe:
1) RESTRUCTURING
2) Simplifiying
3) Extending
4) Correcting
If I can give my suggestions, I would unite these 2 maps + New Features V1.5 and add a Quick Start Guide for the complete beginner in mindmapping and WHAT is mindmapping and HOW TO USE the basic features of Freeplane is the best initial input medium for the real beginner.
That said, I see that there is a truck load of content already available in TUTORIAL and DOCUMENTATION maps from the >Help menu.
I don't think there is much to add in content exept for all the new features of the latest release which are not yet available in the DOCUMENTATION map.
Last edit: maggv 2016-08-11
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Is the one you refer to one of these? I think some of these should be incorporated into one documentation map. It would be much easier to search and filter than working with multiple maps and trying to remember where you read something you want to find again.
If we don't take the necessary time to set a specification, we're just going to continue to chew up resources in various forms that only address some needs and leave others unmet.
I agree completely
user interface is pretty confusing
Some apps have different interfaces users can choose. For example, beginner or advanced. I think that might be nice eventually, but not directly part of this project.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
User name was Jokro (actual name was Jodi)--big time power user of Freeplane coming from educational background with English as one of his many language skills. I think most of those that you show are probably his.
But I think maggv's points are well made: There is a HUGE library of information out there, mostly current.
In my own view and taste, there isn't anything tying them all together in a cohesive structure. How does all that information fit together? In my own experience, mindmaps are often a little bit like spreadsheets. They are intensely personal and speak to the way the creator made data into meaningful information in ways that made sense to THEM. A mindmap starts with a blank slate and the only limitations are those imposed by the software. There are really no predefined "best practices" that guide us in what would help others to follow the logical train of thought through the map. And that is especially true if the user has zero knowledge of what a mindmap is!
When we (well, westerners at any rate--that's another problem to discuss elsewhere) approach a book, for example, we come with certain predisposed ideas of what we expect to see. There's a table of contents, a chapter structure and oftentimes appendices, glossary and cross references at the back. There are specific conventions for portraying supporting information outside the actual text (tables, footnotes, maps, images, bibliographic information, etc) The layout is prescribed and we all know what to expect.
The wiki is already there and is well understood by most internet-aware users. They understand how it works, even as they seek to understand Freeplane. Why confuse them with new things they have to learn before they can learn new things? It seems to me our most straight forward approach would be to clean up what we have so that people can put their toes into mindmapping without overwhelming them with complex maps. Besides, if we make Freeplane a requirement to tell them about mindmaps means they must right-off-the-bat navigate downloading and installing a local copy of the software before they begin learning, which might be a bit off-putting to some and presumptious to others.
I suggest we just start by helping them to see, in a way they are comfortable with, what Freeplane has to offer and then slowly take them through the process of downloading the current stable copy of Freeplane, opening a first map, walking them through what they're seeing an a basic suite of tools that will get them started. Each of those steps are best managed via simple videos that concisely cover the specific skills referenced in the wiki and nothing more. "How to install Freeplane," "Roots, Parents and Children," "Data containers used within Freeplane," "Moving nodes in Freeplane," "Links: what they are, how to use them,", etc. The new user can follow along until they get a map up, maybe even with links they built themselves that THEN points to a master map of maps that will take them to "Infinity and Beyond" in Freeplane skills.
Q!
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
As a user, it seems to me that the user interface is pretty confusing.
If you feel a need to change it tell it. Changing user interface could be pretty easy for devs.
In freeplane there are some (undocumented or hidden) features which allow users to edit their menus and preference panels. Actions and option positions and the most text strings can be changed by user. So if you have an example of what you need to change I could probably show you how you can do it yourself, and we could also include your changes in the next bug fix versions instead of documenting the current state.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I should have realized that the phrase "user interface" has technical meanings for a developer. I wasn't referencing the Freeplane software at all, but the whole "front office" feel of the website.
Q!
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I should have realized that the phrase "user interface" has technical meanings for a developer.
Even if you didn't had the intention to go into this direction I think this should be part of this project: The GUI should be improved by rounding the rough edges and perhaps by adding some mechanisms to guide the user.
I think a Quick Start Guide is missing for the biginner and first time user of mind maps and mind map software. The current Tutorial is useful and in my opinion organized and straight forward in the approach. I cannot say the same for the documentation and specifically referring to the layout and not the content. I think it is important to have a reference (more in depth documentation) guide than only a simple Quick Start guide. Something you can refer to as experience grows.
For my brief experience in mindmaping, layout is as important as the content of the nodes. The map must be well designed to guide the learning process.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Referring to layout, I would put everthing in one mindmap, also to avoid redundancy and repetition.
Also, defining the unfolding of the map is important and it is what I do to reveal only the information needed to guide me in the information > revealing > dicovering > learning process.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
please excuse my late participation is this discussion. Some months ago I was involved in similar discussions concerning a "feature map" for description of Freeplane's great features (to be comparable to other mindmapping solutions) and a "format map" describing the current XML file format in a human readable way. For both these discussions, there are small projects on GitHub. I would be happy if these solutions could be considered for the new documentation pathway. Maybe there is some possibility for merge? Maybe there were included some good ideas which are worthy to be taken into a final over-all documentation solution? Please have a look:
Here are some thoughts about subjects within this thread:
structure of the documentation
As Roberto stated, some people rather prefer a linear documentation of things. They start at the beginning and read it through. Others (like me) prefer a structured way of providing (at least descriptive keywords of) information. At least, a single linear documentation (e.g. PDF or HTML) could be automatically generated from the structured mindmap. So, I would definitely support Ken's approach and help create a great, structured mindmap being the starting point for information retrieval. For both, beginners and experts. Providing links to both, overviews and detail feature information, whether new ones or already existing ones, whether in form of other mindmaps, HTML pages, YouTube videos, PDF or plain text files. Structured knowledge representation and networking. I could imagine all the descriptive documents to reside within the community's Wiki. And a central mindmap holding links to these pages in a structured way. Great, if any person, regardless of his approach could find the information he is looking for. The more different pathways the better, I think.
in-depth documentation vs. documentation of major features
...why not choose the documentation document structure in that way that both would be possible. A description of the "major features" and a in-depth description of "sub features" like split-nodes. "sub features" might be those features which enhance the major differences concerning other solutions. They show the developer's love and offer all the helpful details which help fine-tune the user's process of operation and user interface.
documentation of user interface
Documentation of menu locations (where to access each feature) might be preferrable to the documentation of keyboard shortcuts. Keyboard shortcuts are user-adjustable (each user might build his usage upon his own choice of shortcuts) AND target system dependent (e.g. Windows and MAC have different ones). Menu locations automatically display the current active keyboard shortcut and the user can quickly "fix" its setting.
video documentation with sub-feature entry points
As mentioned by Ken, linking videos to each "major feature" would be a great and quick help for beginners to get an overview. And an additional possibility to jump into a specific video section when searching for a specific "sub feature" would be great for reference purposes. I wouldn't know how to create these references using YouTube, but it should be possible somehow. Great idea!
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
this thread is getting hard to find things and comprehend the whole.
I wonder if there is some survey tool -- doodle, survey monkey, google forms -- where we could get a feel for how everyone thinks about layout and such.
I favor :
mindmap vs document/wiki - I hate wading thru blocks of text to find the key word I want.
Mindmaps are the only way to show relationships you can search for and see in one place. Wiki pages are viewed on their own, even though linked to another page.
one map vs multiple maps - full range of FP info (getting started thru menubar/toolbars/context menus thru ???). Using colors/icons for beginner, intermediate, advanced.
linked videos keyed to map
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Freeplane hosts its own wiki at http://www.freeplane.org/wiki/index.php/Main_Page . (It is hosted by source forge servers in the project web space where no https support is possible yet). So if anyone wants to contribute to it just register and let us know your user names.
The problem with the current wiki is not only that it is feature centric - as Peter said - but it is also badly organized, so you can't read through all the pages that are relevant to you in a sensible order.
I'm afraid that this problem will not simply be fixed by more people but by more planning.
Volker
Volker,
For the past several years I've been working within teams separated by distance and time, sometimes as many as 12 collaborators in as many time zones. I've come to value digital collaboration as a very powerful way to get things done. These teams have been tasked with the development of large, comprehensive plans that define the long-term scope of complex projects over 3-5 years.
Freeplane, in it's current configuration, isn't well suited to collaborative tasks. It's a great personal tool, but awkward in collecting and processing collective thought. So a different tool seems to be needed, at least for the development parts. Wikis in their pure form were made for this, allowing many people to submit material and have them peer reviewed and revised before publishing. I'm not sure SourceForge's implementation is that robust, so perhaps somebody can enlighten. I have a great deal of experience with Google Docs. All the detractions aside, it is the only tool I've found that allows multiple people to work together in an efficient and controlled manner. Add a common language and phone or Skype connection and it's VERY powerful--like holding a meeting where each party can participate while seeing in real time what other collaboraters have added or commented about.
But with that said, I must also say that I've never seen a successful collaboration done without somebody that projects a vision of the end product. This person is really the team's chief editor and is empowered and acknowledged by each member on the team with the ability to arbitrate and, if necessary, ajudicate disputes. Dimitry and you play this role on Freeplane's technical side. This person would establish the vision of how the document will look in its final form and how various subcomponents ("chapters?") would fit together. They would manage a team of volunteer writers, assigning them appropriate tasks, very much like a project manager, with scope of work descriptions and due dates.
So, I'm in agreement with you 100%. What is needed, IMHO, is an individual that is well respected in the community and in whom all have confidence that they have the best view of what the final product should look like. This person would act as project manager, holding both individuals and the team as a whole to account for specific action items and "deliverables." Then we set up the appropriate technical mechanism that will allow people to take a piece for which they have knowledge and insight, draft up an initial submission for review and comment by the appropriate sub-team. Once the subteam is happy with their draft document, the whole thing is submitted to the larger team for review and suggestions.
Once fully vetted, the document could then be "published" to the larger Freeplane community.
The person you describe sounds like you -- although I have a strong suspicion you would not put yourself forward. I think you would be excellent filling the job description you outline. You certainly have experience with collaborative projects. You've always struck me a extremely positive + you have more of a user-focus than a techie-obsession - although I've long considered you to be a FP master. And more than willing to listen to others.
I nominate Quinbus to spearhead this project, if he has the time to spare and is willing.
I think that this project offers a lot of non technical creative challenging and tasks and I agree with you that these tasks have basically not been systematically addressed yet. It would be great if a team came together for it. I think a good working team has much more power, capacity, stability, ideas, momentum and motivation than single persons.
I think it can be helpful to have a clearly defined vision and a derived task pool. Contributors could take tasks from the pool, and add their own tasks and also contribute to the development of the vision.
Personally I do not think that tasks should be assigned. Their motivation to contribute and satisfaction come out of inner conviction to do the right thing and out of the freedom to decide when they do it and not to do anything one doesn't like.
How do you see it?
Last edit: Dimitry Polivaev 2016-08-10
Dimitry -
I'd like to volunteer to be on the team.
Do you envision the basic decision of mindmap vs document/wiki to come out of the team?
Or do you see that decision coming from the forum, either in this thread or another? Or something else?
I think that needs to be one of the basic decisions before getting too far into things. It would be a time waster to write blocks of text and then decide a mindmap would be better. The other way around would not be as bad, since a mindmap could serve as the outline for a blocky document.
I agree. For example, there is plenty I don't know about FP so assigning me such a feature might not be a good idea, although it might force me to dig in and learn (assuming I make the team).
Last edit: Ken Hill 2016-08-10
Ken, currently you are the only non-technical team member. So I thank you for that. I wish the team gets other people soon.
I think that all decisions are taken by people who do the work. And they should be taken so that no team member feels bad about them. All opinions coming from the outside e.g. from the forum only help the team to consider different ideas, views and arguments.
I think that in order to challenge someone to try something new and to dig in you can suggest to take a task without assigning it. You can help the other guy to believe in himself, support him and see him grow not by law and order, just by putting your trust in his judgement, competence and good will.
Last edit: Dimitry Polivaev 2016-08-10
Dimitry,
The concept of "assignment" is a little harsh. I should have softened that a little. This is sitll a volunteer effort and there simply isn't any leverage to force somebody to do something that they don't want to do.
But speaking personally, I find it very hard to volunteer without a structure in place to know where to jump in. This is a litte bit "chicken and egg." Without some sort of framework, we each make interpretations about what we would like to see, some of which the community will support wholeheartedly and some which will have differing levels of support. Some of the proposals currently floated are counter to each other in direction (e.g., linear text vs. wiki vs. mindmap-based).
When you chose to fork Freemind, there were those in the old community that didn't see the benefit of restructing the code for future development. But you and Volker had a vision that has lead to a whole new user community who want to share what you initially saw. We need somebody with that confidence and vision for the documentation interface.
Lots of us ask you and Volker for what we think will be technical improvements. Your combined knowledge of coding, of the API and your vision for the product balanced with overall performance carries a lot of weight when you support, prioritize and sometimes gently decline. We need somebody like you on the documentation side that commands the same level of respect and offers practical ideas, questions and direction.
They don't have to do all the work. They don't have to drive anybody. But they need to have a vision (coupled, hopefully, with practical experience in writing user documentation) that others can grasp. I think there are many of us in the non-technical side that could/would contribute, but we need some sort of structure that is breakable into manageable chunks and priorities set in a way that each volunteer can see how their piece fits with a larger whole. Otherwise we're just all flopping aorund with the many different ideas of how to approach the task.
Q!
I'm with Quinbus - that it is a bit scary to volunteer for something that is fuzzy and nebulous.
I still think some of these questions about very basic decisions would benefit by a survey or poll at some point. Otherwise, how do we get to a workable consensus in order to begin?
Quinbus,
I know there are different kinds of organizations, and I am confident that the one you choose together can work for you best.
I can however share some of my experiences.
In freeplane software development Volker, Felix and me usually discuss all decisions with high impact together whenever any of us wants it and reach an agreement. We choose our next tasks ourselves. People who want to try out new things get their space to try and get the support the rest of they team can give them. Attempts which do not work are sorted out.
At the place where I daily work I am a part of one sofware development team consisting of 7 members. We have agreed on a principle "together we find the best solution". We do not have formal hierarchies at this level. We have practices, processes and game rules. In our regular retrospectives we discuss our processes and rules and change them on a base of agreement. And we also have separate product owner and product managers who are in touch with customers. They decide what should be done next and they have no influence on the details of technical solutions we develop in team.
Anyway I would like to disappear from this discussion for a while so that I do not disturb you finding together and doing your first steps together. I am not a part of documentation development.I can not decide with you how you want to work together and which priorities you set. I just want you to be successful as a team.
Best regards,
Dimirty
This is the way it works, actually. But Freeplane's software was initially formed via a big rework of the basis of FreeMind. You had a vision and invested much more work than we others, so the strengths of Freeplane's architecture is much more the result of one mind than of discussions.
I think the documentation needs the same treatment that FreeMind's sources received mainly by you. And I think that Quinbus is right on how this could work.
By the way: I also believe that the software needs some improvement to improve the ease of use. Just improving the documentation is not enough.
I would be interested in Peter's opinion about this issue.
Volker
Volker, current freeplane architecture has not only strengths. If I could discuss it with you during the redesign phase 2007 and decide together it could probably prevent us from some mistakes. I was working alone and now I doubt it was the most effective way.
Dimitry,
Thanks for that peek behind the curtain. I found it very interesting and insightful.
One thing - as users, we do not see the marvelous things you do in the innerworkings of Freeplane - we only see the user interface.
With documentation, what the reader sees is completely on the surface. I agree that everyone on the documentation team should have lots of freedom and flexibility. But documentation with wildly different writing styles could end up being disjointed and even confusing. This would not be as much of an issue with a mindmap, where keywords are valued, but in a full-blown linear user manual it could be an issue.
One the other hand, based on my own experience, users might be expected to only look at one section at a time so writing style differences may not be noticeable.
And this forum has a lot of users from different nationalities and cultures, as well as a wide range of technical expertise, which could contribute to different writing styles.
At some point, the documentation team -- or perhaps a different team, not so close to the sometimes-emotional writing process -- should be tasked with making a pass thru the documentation trying to bring together style consistency. Especially for a linear manual.
I don't want to over-complicate this project. I bring this up to add this to the mix of considerations. It certainly is not an insurrmountable problem.
Documentation team members should be aware that their contributions are needed and valued - but their words may need to be edited. That should be out in the open from the beginning.
I've worked on other writing projects with people who thought their writing was perfect, and don't you dare touch one word! From my experience on the forum, I don't think that extreme will be a problem. This forum is very civilized and polite and positive.
Hi Ken,
In my opinion, there is a lot of content already available in the current Tutorial map and also in the Documentation map. Why not use what has already been done and reorganize, structure it differently?
maggv,
You're referencing the map that user Jodi created a few years ago? Do others remember that significant project?
This particular user tirelessly worked on making a comprehensive map of Freeplane's features. The thing was comprehensive and well thought through. Are we talking about something different than the use case Jodi's map was trying to address?
There may be a problem in here that unlike the software folks, we have no standard that defines what we're trying to build. If we don't take the necessary time to set a specification, we're just going to continue to chew up resources in various forms that only address some needs and leave others unmet.
As a user, it seems to me that the user interface is pretty confusing. There's the wiki, there are various maps, there is the program itself, there is the community fora on SourceForge (which replaced a BBS before), untold numbers of videos about the product. Where do we want to drive new folks for answers? Where is the place where all materials and guides points to? We pretty much now expect new users to just stumble around and find the answers they need whereever they can find them.
Maybe it's just me, but the problem doesn't seem to be "user documentation." It's the whole front office package that needs to be structured/restructured so as to enhance the experience for people like our recently inflamed poster.
It's a big job. Really big.
Q!
Hi Quinbus,
I don't know Jodi and what map he created. There are 2 maps as a biginner user I initialy started to consult: Main Menu > Help
DOCUMENTATION map is what I use to learn about the various comands in Freeplane. It is extensive and a good reference for in depth understanding of all commands. I would not scrap it, but restructure and mainly focus on the reference part of the map.
TUTORIAL is what I "REALLY" used as a biginner to understand what I can do with a mindmapping software and I think it is pretty well done and straight forward in the approach. There are three sections: Beginner, Advanced, Professional.
If I must add to that also the various videos on Youtube (including yours and Jonas lately) "Great job to both by the way!"
There are probably some corrections to make:
Maybe:
1) RESTRUCTURING
2) Simplifiying
3) Extending
4) Correcting
If I can give my suggestions, I would unite these 2 maps + New Features V1.5 and add a Quick Start Guide for the complete beginner in mindmapping and WHAT is mindmapping and HOW TO USE the basic features of Freeplane is the best initial input medium for the real beginner.
That said, I see that there is a truck load of content already available in TUTORIAL and DOCUMENTATION maps from the >Help menu.
I don't think there is much to add in content exept for all the new features of the latest release which are not yet available in the DOCUMENTATION map.
Last edit: maggv 2016-08-11
Quinbus,
Is the one you refer to one of these? I think some of these should be incorporated into one documentation map. It would be much easier to search and filter than working with multiple maps and trying to remember where you read something you want to find again.
I agree completely
Ken,
User name was Jokro (actual name was Jodi)--big time power user of Freeplane coming from educational background with English as one of his many language skills. I think most of those that you show are probably his.
But I think maggv's points are well made: There is a HUGE library of information out there, mostly current.
In my own view and taste, there isn't anything tying them all together in a cohesive structure. How does all that information fit together? In my own experience, mindmaps are often a little bit like spreadsheets. They are intensely personal and speak to the way the creator made data into meaningful information in ways that made sense to THEM. A mindmap starts with a blank slate and the only limitations are those imposed by the software. There are really no predefined "best practices" that guide us in what would help others to follow the logical train of thought through the map. And that is especially true if the user has zero knowledge of what a mindmap is!
When we (well, westerners at any rate--that's another problem to discuss elsewhere) approach a book, for example, we come with certain predisposed ideas of what we expect to see. There's a table of contents, a chapter structure and oftentimes appendices, glossary and cross references at the back. There are specific conventions for portraying supporting information outside the actual text (tables, footnotes, maps, images, bibliographic information, etc) The layout is prescribed and we all know what to expect.
The wiki is already there and is well understood by most internet-aware users. They understand how it works, even as they seek to understand Freeplane. Why confuse them with new things they have to learn before they can learn new things? It seems to me our most straight forward approach would be to clean up what we have so that people can put their toes into mindmapping without overwhelming them with complex maps. Besides, if we make Freeplane a requirement to tell them about mindmaps means they must right-off-the-bat navigate downloading and installing a local copy of the software before they begin learning, which might be a bit off-putting to some and presumptious to others.
I suggest we just start by helping them to see, in a way they are comfortable with, what Freeplane has to offer and then slowly take them through the process of downloading the current stable copy of Freeplane, opening a first map, walking them through what they're seeing an a basic suite of tools that will get them started. Each of those steps are best managed via simple videos that concisely cover the specific skills referenced in the wiki and nothing more. "How to install Freeplane," "Roots, Parents and Children," "Data containers used within Freeplane," "Moving nodes in Freeplane," "Links: what they are, how to use them,", etc. The new user can follow along until they get a map up, maybe even with links they built themselves that THEN points to a master map of maps that will take them to "Infinity and Beyond" in Freeplane skills.
Q!
If you feel a need to change it tell it. Changing user interface could be pretty easy for devs.
In freeplane there are some (undocumented or hidden) features which allow users to edit their menus and preference panels. Actions and option positions and the most text strings can be changed by user. So if you have an example of what you need to change I could probably show you how you can do it yourself, and we could also include your changes in the next bug fix versions instead of documenting the current state.
Dimitry,
I should have realized that the phrase "user interface" has technical meanings for a developer. I wasn't referencing the Freeplane software at all, but the whole "front office" feel of the website.
Q!
Even if you didn't had the intention to go into this direction I think this should be part of this project: The GUI should be improved by rounding the rough edges and perhaps by adding some mechanisms to guide the user.
Volker
I think a Quick Start Guide is missing for the biginner and first time user of mind maps and mind map software. The current Tutorial is useful and in my opinion organized and straight forward in the approach. I cannot say the same for the documentation and specifically referring to the layout and not the content. I think it is important to have a reference (more in depth documentation) guide than only a simple Quick Start guide. Something you can refer to as experience grows.
For my brief experience in mindmaping, layout is as important as the content of the nodes. The map must be well designed to guide the learning process.
Referring to layout, I would put everthing in one mindmap, also to avoid redundancy and repetition.
Also, defining the unfolding of the map is important and it is what I do to reveal only the information needed to guide me in the information > revealing > dicovering > learning process.
Hi,
please excuse my late participation is this discussion. Some months ago I was involved in similar discussions concerning a "feature map" for description of Freeplane's great features (to be comparable to other mindmapping solutions) and a "format map" describing the current XML file format in a human readable way. For both these discussions, there are small projects on GitHub. I would be happy if these solutions could be considered for the new documentation pathway. Maybe there is some possibility for merge? Maybe there were included some good ideas which are worthy to be taken into a final over-all documentation solution? Please have a look:
What do you think?
Here are some thoughts about subjects within this thread:
structure of the documentation
As Roberto stated, some people rather prefer a linear documentation of things. They start at the beginning and read it through. Others (like me) prefer a structured way of providing (at least descriptive keywords of) information. At least, a single linear documentation (e.g. PDF or HTML) could be automatically generated from the structured mindmap. So, I would definitely support Ken's approach and help create a great, structured mindmap being the starting point for information retrieval. For both, beginners and experts. Providing links to both, overviews and detail feature information, whether new ones or already existing ones, whether in form of other mindmaps, HTML pages, YouTube videos, PDF or plain text files. Structured knowledge representation and networking. I could imagine all the descriptive documents to reside within the community's Wiki. And a central mindmap holding links to these pages in a structured way. Great, if any person, regardless of his approach could find the information he is looking for. The more different pathways the better, I think.
in-depth documentation vs. documentation of major features
...why not choose the documentation document structure in that way that both would be possible. A description of the "major features" and a in-depth description of "sub features" like split-nodes. "sub features" might be those features which enhance the major differences concerning other solutions. They show the developer's love and offer all the helpful details which help fine-tune the user's process of operation and user interface.
documentation of user interface
Documentation of menu locations (where to access each feature) might be preferrable to the documentation of keyboard shortcuts. Keyboard shortcuts are user-adjustable (each user might build his usage upon his own choice of shortcuts) AND target system dependent (e.g. Windows and MAC have different ones). Menu locations automatically display the current active keyboard shortcut and the user can quickly "fix" its setting.
video documentation with sub-feature entry points
As mentioned by Ken, linking videos to each "major feature" would be a great and quick help for beginners to get an overview. And an additional possibility to jump into a specific video section when searching for a specific "sub feature" would be great for reference purposes. I wouldn't know how to create these references using YouTube, but it should be possible somehow. Great idea!
this thread is getting hard to find things and comprehend the whole.
I wonder if there is some survey tool -- doodle, survey monkey, google forms -- where we could get a feel for how everyone thinks about layout and such.
I favor :
mindmap vs document/wiki - I hate wading thru blocks of text to find the key word I want.
Mindmaps are the only way to show relationships you can search for and see in one place. Wiki pages are viewed on their own, even though linked to another page.
one map vs multiple maps - full range of FP info (getting started thru menubar/toolbars/context menus thru ???). Using colors/icons for beginner, intermediate, advanced.
linked videos keyed to map