From: Yaron K. <ya...@wi...> - 2011-09-07 00:38:44
|
Hi everyone, I restructured the Semantic Forms documentation, separating it into subpages. The main page now holds just links to the subpages, as well as a quick "cheat sheet" at the bottom: http://www.mediawiki.org/wiki/Extension:Semantic_Forms I resisted doing this for a long time, because I had gotten used to having everything on one page. But as the amount of information grew, the documentation became unwieldy to read - and, as I realized, possibly too unwieldy to edit either. The new setup hopefully makes it easier for people to do both. Any comments about the new structure of the documentation are welcome - maybe the "Defining forms" subpage, which is by far the longest, should get split up; or, conversely, maybe some of the very short subpages should get merged together, etc. -Yaron |
From: badon <fas...@gm...> - 2011-09-07 02:39:58
|
Thank you very much for this - it's a step in the right direction. I actually prefer longer pages over short ones because it makes it easier to find things visually, even if I didn't know I was looking for it. But, opening the door for further improvement is a good gain for the price of breaking it up into subpages. Yaron Koren-2 wrote: > > Hi everyone, > > I restructured the Semantic Forms documentation, separating it into > subpages. The main page now holds just links to the subpages, as well as a > quick "cheat sheet" at the bottom: > > http://www.mediawiki.org/wiki/Extension:Semantic_Forms > > I resisted doing this for a long time, because I had gotten used to having > everything on one page. But as the amount of information grew, the > documentation became unwieldy to read - and, as I realized, possibly too > unwieldy to edit either. The new setup hopefully makes it easier for > people > to do both. > > Any comments about the new structure of the documentation are welcome - > maybe the "Defining forms" subpage, which is by far the longest, should > get > split up; or, conversely, maybe some of the very short subpages should get > merged together, etc. > > -Yaron > ------------------------------------------------------------------------------ > Using storage to extend the benefits of virtualization and iSCSI > Virtualization increases hardware utilization and delivers a new level of > agility. Learn what those decisions are and how to modernize your storage > and backup environments for virtualization. > http://www.accelacomm.com/jaw/sfnl/114/51434361/ > _______________________________________________ > Semediawiki-user mailing list > Sem...@li... > https://lists.sourceforge.net/lists/listinfo/semediawiki-user > > -- View this message in context: http://old.nabble.com/-SF--Documentation-overhauled-tp32412560p32412933.html Sent from the Semantic Mediawiki - User mailing list archive at Nabble.com. |
From: Sal Q. <sal...@gm...> - 2011-09-07 01:02:03
|
I'll always encourage making documentation as manageable and readable as possible. But in this case, I see a problem regarding page search. When I used the old page, I'd search for phrases that often led me to 2 or more sections to get the full concept. Now groups of sections are on separate pages, and to search for certain phrases thoroughly I might have to open 1 or more pages... and paranoia might lead me to open pages that don't seem to be related, "just in case". If the page set were its own site, or if search could be limited to the Extension:Semantic Forms/* articles, this wouldn't be a problem (and if that's already syntactically possible, please share, I could use that feature on my own site). As it is now, it might take some work to find all things related to the string I'm searching for, compared to just clicking "next". Regards, Sal -----Original Message----- From: Yaron Koren [mailto:ya...@wi...] Sent: Tuesday, September 06, 2011 5:39 PM To: Semantic MediaWiki users Subject: [Semediawiki-user] [SF] Documentation overhauled Hi everyone, I restructured the Semantic Forms documentation, separating it into subpages. The main page now holds just links to the subpages, as well as a quick "cheat sheet" at the bottom: http://www.mediawiki.org/wiki/Extension:Semantic_Forms I resisted doing this for a long time, because I had gotten used to having everything on one page. But as the amount of information grew, the documentation became unwieldy to read - and, as I realized, possibly too unwieldy to edit either. The new setup hopefully makes it easier for people to do both. Any comments about the new structure of the documentation are welcome - maybe the "Defining forms" subpage, which is by far the longest, should get split up; or, conversely, maybe some of the very short subpages should get merged together, etc. -Yaron ---------------------------------------------------------------------------- -- Using storage to extend the benefits of virtualization and iSCSI Virtualization increases hardware utilization and delivers a new level of agility. Learn what those decisions are and how to modernize your storage and backup environments for virtualization. http://www.accelacomm.com/jaw/sfnl/114/51434361/ _______________________________________________ Semediawiki-user mailing list Sem...@li... https://lists.sourceforge.net/lists/listinfo/semediawiki-user |
From: Yaron K. <ya...@wi...> - 2011-09-07 02:22:37
|
Hi Sal, Yes, being able to do a full text search is indeed a big advantage of having everything on one page - that was another reason why I wanted to keep things as they were for a long time. I tried to make the section descriptions on the front page comprehensive, so that if you did a text search for, say, "formlink", you would find the relevant section - and I also tried to put in a bunch of "see also" type links within the different sections. Still, it's not quite the same. Yes, it's possible to do a MediaWiki search on all pages within "Extension:Semantic Forms/...". You can see the "Search archives" input in the talk page for an example of that sort of thing: http://www.mediawiki.org/wiki/Extension_talk:Semantic_Forms Still, it's not nearly as convenient as a simple browser text search. If there are specific strings you remember searching for, that now would be harder to find, I'm curious to hear what they were. -Yaron On Tue, Sep 6, 2011 at 9:01 PM, Sal Quintanilla <sal...@gm...> wrote: > I'll always encourage making documentation as manageable and readable as > possible. But in this case, I see a problem regarding page search. When I > used the old page, I'd search for phrases that often led me to 2 or more > sections to get the full concept. Now groups of sections are on separate > pages, and to search for certain phrases thoroughly I might have to open 1 > or more pages... and paranoia might lead me to open pages that don't seem > to > be related, "just in case". > > If the page set were its own site, or if search could be limited to the > Extension:Semantic Forms/* articles, this wouldn't be a problem (and if > that's already syntactically possible, please share, I could use that > feature on my own site). As it is now, it might take some work to find all > things related to the string I'm searching for, compared to just clicking > "next". > > Regards, > Sal > > > -----Original Message----- > From: Yaron Koren [mailto:ya...@wi...] > Sent: Tuesday, September 06, 2011 5:39 PM > To: Semantic MediaWiki users > Subject: [Semediawiki-user] [SF] Documentation overhauled > > Hi everyone, > > I restructured the Semantic Forms documentation, separating it into > subpages. The main page now holds just links to the subpages, as well as a > quick "cheat sheet" at the bottom: > > http://www.mediawiki.org/wiki/Extension:Semantic_Forms > > I resisted doing this for a long time, because I had gotten used to having > everything on one page. But as the amount of information grew, the > documentation became unwieldy to read - and, as I realized, possibly too > unwieldy to edit either. The new setup hopefully makes it easier for people > to do both. > > Any comments about the new structure of the documentation are welcome - > maybe the "Defining forms" subpage, which is by far the longest, should get > split up; or, conversely, maybe some of the very short subpages should get > merged together, etc. > > -Yaron > > ---------------------------------------------------------------------------- > -- > Using storage to extend the benefits of virtualization and iSCSI > Virtualization increases hardware utilization and delivers a new level of > agility. Learn what those decisions are and how to modernize your storage > and backup environments for virtualization. > http://www.accelacomm.com/jaw/sfnl/114/51434361/ > _______________________________________________ > Semediawiki-user mailing list > Sem...@li... > https://lists.sourceforge.net/lists/listinfo/semediawiki-user > > -- WikiWorks · MediaWiki Consulting · http://wikiworks.com |
From: Sal Q. <sal...@gm...> - 2011-09-07 03:07:36
|
Hi Yaron, I was completely green to SMW / SF a year ago. Though I'm still learning new things, I've got a pretty sophisticated intranet site now, and don't need to check the extension pages very often. But for a long time, as I was coming up to speed on different options, I was on various extension pages many times a day. I don't have any specific examples at the moment, I just recall many times when searches took me to places on the page where the vertical scroll bar position changed significantly, and I'd guess at least some of that movement suggests information on different pages today. And now that I think about it, many times I searched for very different things while working. All I needed to do was type a quick search in my already-open page all day long (and sometimes multiple days), and it was very convenient. The new crop of beginners will have the new format to use, and perhaps they'll adapt just fine. Though if it wasn't too much overhead, I'd suggest having a link to an optional everything page, made up of transcluded section pages. That would be useful to the hard-copy fans also (I'm not one of them). - Sal From: ya...@gm... [mailto:ya...@gm...] On Behalf Of Yaron Koren Sent: Tuesday, September 06, 2011 7:23 PM To: sal...@gm... Cc: Semantic MediaWiki users Subject: Re: [Semediawiki-user] [SF] Documentation overhauled Hi Sal, Yes, being able to do a full text search is indeed a big advantage of having everything on one page - that was another reason why I wanted to keep things as they were for a long time. I tried to make the section descriptions on the front page comprehensive, so that if you did a text search for, say, "formlink", you would find the relevant section - and I also tried to put in a bunch of "see also" type links within the different sections. Still, it's not quite the same. Yes, it's possible to do a MediaWiki search on all pages within "Extension:Semantic Forms/...". You can see the "Search archives" input in the talk page for an example of that sort of thing: http://www.mediawiki.org/wiki/Extension_talk:Semantic_Forms Still, it's not nearly as convenient as a simple browser text search. If there are specific strings you remember searching for, that now would be harder to find, I'm curious to hear what they were. -Yaron On Tue, Sep 6, 2011 at 9:01 PM, Sal Quintanilla <sal...@gm...> wrote: I'll always encourage making documentation as manageable and readable as possible. But in this case, I see a problem regarding page search. When I used the old page, I'd search for phrases that often led me to 2 or more sections to get the full concept. Now groups of sections are on separate pages, and to search for certain phrases thoroughly I might have to open 1 or more pages... and paranoia might lead me to open pages that don't seem to be related, "just in case". If the page set were its own site, or if search could be limited to the Extension:Semantic Forms/* articles, this wouldn't be a problem (and if that's already syntactically possible, please share, I could use that feature on my own site). As it is now, it might take some work to find all things related to the string I'm searching for, compared to just clicking "next". Regards, Sal -----Original Message----- From: Yaron Koren [mailto:ya...@wi...] Sent: Tuesday, September 06, 2011 5:39 PM To: Semantic MediaWiki users Subject: [Semediawiki-user] [SF] Documentation overhauled Hi everyone, I restructured the Semantic Forms documentation, separating it into subpages. The main page now holds just links to the subpages, as well as a quick "cheat sheet" at the bottom: http://www.mediawiki.org/wiki/Extension:Semantic_Forms I resisted doing this for a long time, because I had gotten used to having everything on one page. But as the amount of information grew, the documentation became unwieldy to read - and, as I realized, possibly too unwieldy to edit either. The new setup hopefully makes it easier for people to do both. Any comments about the new structure of the documentation are welcome - maybe the "Defining forms" subpage, which is by far the longest, should get split up; or, conversely, maybe some of the very short subpages should get merged together, etc. -Yaron ---------------------------------------------------------------------------- -- Using storage to extend the benefits of virtualization and iSCSI Virtualization increases hardware utilization and delivers a new level of agility. Learn what those decisions are and how to modernize your storage and backup environments for virtualization. http://www.accelacomm.com/jaw/sfnl/114/51434361/ _______________________________________________ Semediawiki-user mailing list Sem...@li... https://lists.sourceforge.net/lists/listinfo/semediawiki-user -- WikiWorks . MediaWiki Consulting . http://wikiworks.com |
From: kghbln <med...@kg...> - 2011-09-07 08:44:03
|
Heiya to you, first of all: Thank you Yaron for overhauling the documentation. Indeed the more experienced you are the better it is to have the documentation divided up to different pages for the sake of usability and vice versa. Thus I would propose publishing a collection of the documentation as a pdf file with every new version of SF or at least with every new major version and linking to it. Then it would be possible to have a search through the entire documenation via the pdf-viewer of choice. This seems to me an ideal usecase for the collection extension (Special:Book) already installed on mediawikiwiki. Voila, you have the best of two worlds. :) Cheers [[kgh]] Am 07.09.2011 05:07, schrieb Sal Quintanilla: > Hi Yaron, > > > > I was completely green to SMW / SF a year ago. Though I'm still learning > new things, I've got a pretty sophisticated intranet site now, and don't > need to check the extension pages very often. But for a long time, as I was > coming up to speed on different options, I was on various extension pages > many times a day. I don't have any specific examples at the moment, I just > recall many times when searches took me to places on the page where the > vertical scroll bar position changed significantly, and I'd guess at least > some of that movement suggests information on different pages today. > > > > And now that I think about it, many times I searched for very different > things while working. All I needed to do was type a quick search in my > already-open page all day long (and sometimes multiple days), and it was > very convenient. > > > > The new crop of beginners will have the new format to use, and perhaps > they'll adapt just fine. Though if it wasn't too much overhead, I'd suggest > having a link to an optional everything page, made up of transcluded section > pages. That would be useful to the hard-copy fans also (I'm not one of > them). > > > > - Sal > > > > From: ya...@gm... [mailto:ya...@gm...] On Behalf Of Yaron Koren > Sent: Tuesday, September 06, 2011 7:23 PM > To: sal...@gm... > Cc: Semantic MediaWiki users > Subject: Re: [Semediawiki-user] [SF] Documentation overhauled > > > > Hi Sal, > > > > Yes, being able to do a full text search is indeed a big advantage of having > everything on one page - that was another reason why I wanted to keep things > as they were for a long time. I tried to make the section descriptions on > the front page comprehensive, so that if you did a text search for, say, > "formlink", you would find the relevant section - and I also tried to put in > a bunch of "see also" type links within the different sections. Still, it's > not quite the same. > > > > Yes, it's possible to do a MediaWiki search on all pages within > "Extension:Semantic Forms/...". You can see the "Search archives" input in > the talk page for an example of that sort of thing: > > > > http://www.mediawiki.org/wiki/Extension_talk:Semantic_Forms > > > > Still, it's not nearly as convenient as a simple browser text search. If > there are specific strings you remember searching for, that now would be > harder to find, I'm curious to hear what they were. > > > > -Yaron > > > > On Tue, Sep 6, 2011 at 9:01 PM, Sal Quintanilla<sal...@gm...> wrote: > > I'll always encourage making documentation as manageable and readable as > possible. But in this case, I see a problem regarding page search. When I > used the old page, I'd search for phrases that often led me to 2 or more > sections to get the full concept. Now groups of sections are on separate > pages, and to search for certain phrases thoroughly I might have to open 1 > or more pages... and paranoia might lead me to open pages that don't seem to > be related, "just in case". > > If the page set were its own site, or if search could be limited to the > Extension:Semantic Forms/* articles, this wouldn't be a problem (and if > that's already syntactically possible, please share, I could use that > feature on my own site). As it is now, it might take some work to find all > things related to the string I'm searching for, compared to just clicking > "next". > > Regards, > Sal > > > > -----Original Message----- > From: Yaron Koren [mailto:ya...@wi...] > Sent: Tuesday, September 06, 2011 5:39 PM > To: Semantic MediaWiki users > Subject: [Semediawiki-user] [SF] Documentation overhauled > > Hi everyone, > > I restructured the Semantic Forms documentation, separating it into > subpages. The main page now holds just links to the subpages, as well as a > quick "cheat sheet" at the bottom: > > http://www.mediawiki.org/wiki/Extension:Semantic_Forms > > I resisted doing this for a long time, because I had gotten used to having > everything on one page. But as the amount of information grew, the > documentation became unwieldy to read - and, as I realized, possibly too > unwieldy to edit either. The new setup hopefully makes it easier for people > to do both. > > Any comments about the new structure of the documentation are welcome - > maybe the "Defining forms" subpage, which is by far the longest, should get > split up; or, conversely, maybe some of the very short subpages should get > merged together, etc. > > -Yaron > > ---------------------------------------------------------------------------- > -- > Using storage to extend the benefits of virtualization and iSCSI > Virtualization increases hardware utilization and delivers a new level of > agility. Learn what those decisions are and how to modernize your storage > and backup environments for virtualization. > http://www.accelacomm.com/jaw/sfnl/114/51434361/ > _______________________________________________ > Semediawiki-user mailing list > Sem...@li... > https://lists.sourceforge.net/lists/listinfo/semediawiki-user > > > > > > > |